From 94c866613a0de2c1351664f5c469cfd1e5d2841b Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 30 Jun 2026 19:58:37 -0700 Subject: [PATCH 001/337] Added `LoadState` enum to replace `IsFullyLoaded` Currently, state is tracked via a `IsFullyLoaded` bit. I'm introducing a new `LoadState` enum to replace that. Initially, this will essentially still be a one-bit state, but it's a bit more articulate about what the options are, and leaves room for e.g., `Stale` or `PartiallyLoaded` in the future, should we need it. --- OnTopic/LoadState.cs | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 OnTopic/LoadState.cs diff --git a/OnTopic/LoadState.cs b/OnTopic/LoadState.cs new file mode 100644 index 00000000..88f0580f --- /dev/null +++ b/OnTopic/LoadState.cs @@ -0,0 +1,37 @@ +/*============================================================================================================================== +| Author Ignia, LLC +| Client Ignia, LLC +| Project Topics Library +\=============================================================================================================================*/ +using OnTopic.Repositories; + +namespace OnTopic; + +/*============================================================================================================================== +| ENUM: LOAD STATE +\-----------------------------------------------------------------------------------------------------------------------------*/ +/// +/// Indicates the state to which a topic collection has been populated from the underlying , +/// allowing callers to distinguish data that is present and authoritative from data that must still be loaded. +/// +public enum LoadState { + + /*---------------------------------------------------------------------------------------------------------------------------- + | NOT LOADED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// The collection has not been retrieved from the persistence store. Its current contents, typically empty, are not + /// authoritative, and accessing the collection should trigger an on-demand load of its immediate members. + /// + NotLoaded, + + /*---------------------------------------------------------------------------------------------------------------------------- + | LOADED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// The collection has been fully retrieved and is authoritative. This is the default for a newly constructed, in-memory + /// topic, which has nothing deferred in the persistence store. + /// + Loaded, + +} //Enum \ No newline at end of file From 486f963ca516008875b8850c32f029976dc54ff6 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 30 Jun 2026 20:29:59 -0700 Subject: [PATCH 002/337] Establish `LoadState` property for tracking state Added the new `LoadState` enum (94c86661) as a property on `TopicReferenceCollection`, `TopicRelationshipMultiMap`, `AttributeCollection`, and `KeyedTopicCollection` in order to track, respectively, the load state of topic references, relationships, extended attributes, and (typically) children. The `TopicReferenceCollection` and `TopicRelationshipMultiMap` are already tracked by `IsFullyLoaded`, which will be marked as obsolete in a future update; for `AttributeCollection` and `KeyedTopicCollection`, these never had such tracking. --- OnTopic/Associations/TopicReferenceCollection.cs | 16 ++++++++++++++++ .../Associations/TopicRelationshipMultiMap.cs | 16 ++++++++++++++++ OnTopic/Attributes/AttributeCollection.cs | 16 ++++++++++++++++ OnTopic/Collections/KeyedTopicCollection{T}.cs | 16 ++++++++++++++++ 4 files changed, 64 insertions(+) diff --git a/OnTopic/Associations/TopicReferenceCollection.cs b/OnTopic/Associations/TopicReferenceCollection.cs index f196dabb..64915682 100644 --- a/OnTopic/Associations/TopicReferenceCollection.cs +++ b/OnTopic/Associations/TopicReferenceCollection.cs @@ -39,6 +39,22 @@ public TopicReferenceCollection(Topic parentTopic) : base(parentTopic) { } protected override TrackedRecordCollection? BaseCollection => AssociatedTopic.BaseTopic?.References; + /*============================================================================================================================ + | PROPERTY: LOAD STATE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Indicates whether the collection has been populated from the underlying , + /// allowing callers to distinguish data that is present and authoritative from data that must still be fetched. + /// + /// + /// Defaults to . The repository sets this to when any + /// referenced topic cannot be resolved to an in-memory instance during load. The persistence store may optionally + /// provide an indicator of the count without returning the full data, thus allowing this to be set to if, in fact, there are no topic references. While in that state, the + /// will not delete unmatched references on save, preventing unintended data loss. + /// + public LoadState LoadState { get; set; } = LoadState.Loaded; + /*============================================================================================================================ | IS FULLY LOADED? \---------------------------------------------------------------------------------------------------------------------------*/ diff --git a/OnTopic/Associations/TopicRelationshipMultiMap.cs b/OnTopic/Associations/TopicRelationshipMultiMap.cs index 9d05c67b..a743eba3 100644 --- a/OnTopic/Associations/TopicRelationshipMultiMap.cs +++ b/OnTopic/Associations/TopicRelationshipMultiMap.cs @@ -238,6 +238,22 @@ internal void SetValue(string relationshipKey, Topic topic, bool? markDirty, boo public void SetTopic(string relationshipKey, Topic topic, bool? isDirty, bool isIncoming) => SetValue(relationshipKey, topic, isDirty, isIncoming); + /*============================================================================================================================ + | PROPERTY: LOAD STATE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Indicates whether the collection has been populated from the underlying , + /// allowing callers to distinguish data that is present and authoritative from data that must still be fetched. + /// + /// + /// Defaults to . The repository conditionally sets this to + /// when any related topic cannot be resolved to an in-memory instance during load. The persistence store may optionally + /// provide an indicator of the count without returning the full data, thus allowing this to be set to if, in fact, there are no related topics. While in that state, the + /// will not delete unmatched relationships on save, preventing unintended data loss. + /// + public LoadState LoadState { get; set; } = LoadState.Loaded; + /*============================================================================================================================ | IS FULLY LOADED? \---------------------------------------------------------------------------------------------------------------------------*/ diff --git a/OnTopic/Attributes/AttributeCollection.cs b/OnTopic/Attributes/AttributeCollection.cs index 627a3f99..65b2ef08 100644 --- a/OnTopic/Attributes/AttributeCollection.cs +++ b/OnTopic/Attributes/AttributeCollection.cs @@ -57,6 +57,22 @@ internal AttributeCollection(Topic parentTopic) : base(parentTopic) { protected override TrackedRecordCollection? BaseCollection => AssociatedTopic.BaseTopic?.Attributes; + /*============================================================================================================================ + | PROPERTY: LOAD STATE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Indicates whether the collection has been populated from the underlying , + /// allowing callers to distinguish data that is present and authoritative from data that must still be fetched. + /// + /// + /// Defaults to . When a topic is loaded without extended attributes (e.g., on a shallow + /// load), the repository conditionally sets this to to indicate that the extended + /// attribute blob has not yet been retrieved. The persistence store may optionally provide an indicator of the count + /// without returning the full data, thus allowing this to be set to if, in fact, there are + /// no extended attributes. Indexed attributes are never deferred regardless of this state. + /// + public LoadState LoadState { get; set; } = LoadState.Loaded; + /*============================================================================================================================ | METHOD: IS DIRTY \---------------------------------------------------------------------------------------------------------------------------*/ diff --git a/OnTopic/Collections/KeyedTopicCollection{T}.cs b/OnTopic/Collections/KeyedTopicCollection{T}.cs index 5dae6309..26e49b55 100644 --- a/OnTopic/Collections/KeyedTopicCollection{T}.cs +++ b/OnTopic/Collections/KeyedTopicCollection{T}.cs @@ -30,6 +30,22 @@ public KeyedTopicCollection(IEnumerable? topics = null) : base(StringComparer } } + /*============================================================================================================================ + | PROPERTY: LOAD STATE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Indicates whether the collection has been populated from the underlying , + /// allowing callers to distinguish data that is present and authoritative from data that must still be fetched. + /// + /// + /// Defaults to , reflecting that a newly constructed, in-memory collection has nothing + /// deferred. When a topic is loaded shallowly from the persistence store, the repository conditionally sets this to + /// to indicate that the immediate children have not yet been fetched. The persistence + /// store may optionally provide an indicator of the count without returning the full data, thus allowing this to be set to + /// if, in fact, there are no relevant topics. + /// + public LoadState LoadState { get; set; } = LoadState.Loaded; + /*============================================================================================================================ | METHOD: GET VALUE \---------------------------------------------------------------------------------------------------------------------------*/ From a013fe065c05d65891dcf0478bb0684732e2f934 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 30 Jun 2026 20:42:16 -0700 Subject: [PATCH 003/337] Update callers to use new `LoadState` property Instead of relying on `IsFullyLoaded`, callers should instead adopt the new `LoadState` property (486f963c). This only affects references to `TopicReferenceCollection` and `TopicRelationshipMultiMap`; neither `AttributeCollection` or `KeyedTopicCollection` ever had `IsFullyLoaded`, and so they will require subsequent updates. In addition, to be safe, the two `IsFullyLoaded` properties now delegate to the new `LoadState` property, so there's never a chance of them being out of step. In a future update, however, we'll be marking `IsFullyLoaded` as obsolete to further discourage its use. --- OnTopic.Data.Sql/SqlDataReaderExtensions.cs | 4 ++-- OnTopic.Data.Sql/SqlTopicRepository.cs | 8 +++---- OnTopic.Tests/SqlTopicRepositoryTest.cs | 22 +++++++++---------- .../Associations/TopicReferenceCollection.cs | 5 ++++- .../Associations/TopicRelationshipMultiMap.cs | 11 ++++++---- 5 files changed, 28 insertions(+), 22 deletions(-) diff --git a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs index b6ee0d64..eca0226c 100644 --- a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs +++ b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs @@ -357,7 +357,7 @@ private static void SetRelationships(this IDataReader reader, TopicIndex topics, // Bypass if the target object is missing if (related is null) { - current.Relationships.IsFullyLoaded = false; + current.Relationships.LoadState = LoadState.NotLoaded; return; } @@ -413,7 +413,7 @@ private static void SetReferences(this IDataReader reader, TopicIndex topics, bo referenced = referencedTopic; } else { - current.References.IsFullyLoaded = false; + current.References.LoadState = LoadState.NotLoaded; return; } diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index ba5c00a1..ec397770 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -253,8 +253,8 @@ public override Topic Load(int topicId, DateTime version, Topic? referenceTopic \-------------------------------------------------------------------------------------------------------------------------*/ catch (SqlException exception) { if (topic is not null) { - topic.Relationships.IsFullyLoaded = false; - topic.References.IsFullyLoaded = false; + topic.Relationships.LoadState = LoadState.NotLoaded; + topic.References.LoadState = LoadState.NotLoaded; } throw new TopicRepositoryException($"Topics failed to load: '{exception.Message}'", exception); } @@ -657,7 +657,7 @@ private static void PersistRelationships(Topic topic, DateTime version, SqlConne command.AddParameter("RelationshipKey", key); command.AddParameter("RelatedTopics", targetIds); command.AddParameter("Version", version); - command.AddParameter("DeleteUnmatched", topic.Relationships.IsFullyLoaded); + command.AddParameter("DeleteUnmatched", topic.Relationships.LoadState is LoadState.Loaded); command.ExecuteNonQuery(); @@ -713,7 +713,7 @@ private static void PersistReferences(Topic topic, DateTime version, SqlConnecti command.AddParameter("TopicID", topic.Id.ToString(CultureInfo.InvariantCulture)); command.AddParameter("ReferencedTopics", references); command.AddParameter("Version", version); - command.AddParameter("DeleteUnmatched", topic.References.IsFullyLoaded); + command.AddParameter("DeleteUnmatched", topic.References.LoadState is LoadState.Loaded); command.ExecuteNonQuery(); diff --git a/OnTopic.Tests/SqlTopicRepositoryTest.cs b/OnTopic.Tests/SqlTopicRepositoryTest.cs index 86cbb637..b740842b 100644 --- a/OnTopic.Tests/SqlTopicRepositoryTest.cs +++ b/OnTopic.Tests/SqlTopicRepositoryTest.cs @@ -153,7 +153,7 @@ public void LoadTopicGraph_WithRelationship_ReturnsRelationship() { Assert.NotNull(topic); Assert.Equal(1, topic?.Id); Assert.Equal(2, topic?.Relationships.GetValues("Test").FirstOrDefault()?.Id); - Assert.True(topic?.Relationships.IsFullyLoaded); + Assert.Equal(LoadState.Loaded, topic?.Relationships.LoadState); } @@ -161,9 +161,9 @@ public void LoadTopicGraph_WithRelationship_ReturnsRelationship() { | TEST: LOAD TOPIC GRAPH: WITH MISSING RELATIONSHIP: NOT FULLY LOADED \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Calls with a record that is missing and confirms that returns false. + /// Calls with a record that is missing and confirms that + /// returns . /// [Fact] public void LoadTopicGraph_WithMissingRelationship_NotFullyLoaded() { @@ -182,7 +182,7 @@ public void LoadTopicGraph_WithMissingRelationship_NotFullyLoaded() { Assert.NotNull(topic); Assert.Equal(1, topic.Id); Assert.Empty(topic.Relationships); - Assert.False(topic.Relationships.IsFullyLoaded); + Assert.Equal(LoadState.NotLoaded, topic.Relationships.LoadState); } @@ -241,7 +241,7 @@ public void LoadTopicGraph_WithExternalReference_ReturnsReference() { Assert.NotNull(topic); Assert.Equal(1, topic?.Id); Assert.Equal(2, topic?.References.GetValue("Test")?.Id); - Assert.True(topic?.References.IsFullyLoaded); + Assert.Equal(LoadState.Loaded, topic?.References.LoadState); Assert.False(topic?.References.IsDirty()); } @@ -273,7 +273,7 @@ public void LoadTopicGraph_WithDeletedReference_RemovesExistingReference() { tableReader.LoadTopicGraph(referenceTopic, false); Assert.Null(referenceTopic.References.GetValue("Reference")); - Assert.True(referenceTopic.References.IsFullyLoaded); + Assert.Equal(LoadState.Loaded, referenceTopic.References.LoadState); } @@ -281,9 +281,9 @@ public void LoadTopicGraph_WithDeletedReference_RemovesExistingReference() { | TEST: LOAD TOPIC GRAPH: WITH MISSING REFERENCE: NOT FULLY LOADED \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Calls with a record that is missing and confirms that returns false. + /// Calls with a record that is missing and confirms that + /// returns . /// [Fact] public void LoadTopicGraph_WithMissingReference_NotFullyLoaded() { @@ -302,7 +302,7 @@ public void LoadTopicGraph_WithMissingReference_NotFullyLoaded() { Assert.NotNull(topic); Assert.Equal(1, topic.Id); Assert.Empty(topic.References); - Assert.False(topic.References.IsFullyLoaded); + Assert.Equal(LoadState.NotLoaded, topic.References.LoadState); } diff --git a/OnTopic/Associations/TopicReferenceCollection.cs b/OnTopic/Associations/TopicReferenceCollection.cs index 64915682..356f0910 100644 --- a/OnTopic/Associations/TopicReferenceCollection.cs +++ b/OnTopic/Associations/TopicReferenceCollection.cs @@ -75,7 +75,10 @@ public TopicReferenceCollection(Topic parentTopic) : base(parentTopic) { } /// back to a valid reference in memory. /// /// - public bool IsFullyLoaded { get; set; } = true; + public bool IsFullyLoaded { + get => LoadState is LoadState.Loaded; + set => LoadState = value? LoadState.Loaded : LoadState.NotLoaded; + } /*============================================================================================================================ | INSERT ITEM diff --git a/OnTopic/Associations/TopicRelationshipMultiMap.cs b/OnTopic/Associations/TopicRelationshipMultiMap.cs index a743eba3..0b975baf 100644 --- a/OnTopic/Associations/TopicRelationshipMultiMap.cs +++ b/OnTopic/Associations/TopicRelationshipMultiMap.cs @@ -269,12 +269,15 @@ public void SetTopic(string relationshipKey, Topic topic, bool? isDirty, bool is /// ITopicRepository"/> should not deleted unmatched relationships. /// /// - /// The property defaults to true. It should be set to false during the method if any members of the collection cannot be mapped back to - /// a valid reference in memory. + /// The property defaults to true. It should be set to false during the method if any members of the collection cannot be mapped + /// back to a valid reference in memory. /// /// - public bool IsFullyLoaded { get; set; } = true; + public bool IsFullyLoaded { + get => LoadState is LoadState.Loaded; + set => LoadState = value? LoadState.Loaded : LoadState.NotLoaded; + } /*============================================================================================================================ | METHOD: IS DIRTY? From c33f4a430b6da3396f2cd0cf8f35f0f37ee0b2d0 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 30 Jun 2026 21:38:03 -0700 Subject: [PATCH 004/337] Ensure that ancestors are loaded When lazy-loading relationships, we don't want a topic that's orphaned from the tree, as then we can't add it to the object graph. When loading an individual topic, we will ensure that we're also retrieving its entire ancestral tree so that we are certain to be able to locate and populate it within the topic graph, regardless of it's current state. Unfortunately, prior to this, there's no way for us to know from its ID where in the topic graph it lives and, therefore, which of its ancestors we may already have in memory. --- .../Stored Procedures/GetTopics.sql | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/OnTopic.Data.Sql.Database/Stored Procedures/GetTopics.sql b/OnTopic.Data.Sql.Database/Stored Procedures/GetTopics.sql index 0d6d9a28..fdfcc699 100644 --- a/OnTopic.Data.Sql.Database/Stored Procedures/GetTopics.sql +++ b/OnTopic.Data.Sql.Database/Stored Procedures/GetTopics.sql @@ -65,7 +65,10 @@ IF @DeepLoad = 1 END -------------------------------------------------------------------------------------------------------------------------------- --- SELECT TOPIC ONLY +-- SELECT TOPIC AND ANCESTOR CHAIN +-------------------------------------------------------------------------------------------------------------------------------- +-- Ancestors are rows whose nested-set range contains the requested node's RangeLeft, i.e., the mirror of the descendant query +-- above. This guarantees the full parent chain is always materialized, even on a shallow (non-recursive) load. -------------------------------------------------------------------------------------------------------------------------------- ELSE BEGIN @@ -73,10 +76,15 @@ ELSE TopicID, SortOrder ) - SELECT TopicID, - 1 - FROM Topics - WHERE TopicID = @TopicID + SELECT T1.TopicID, + T1.RangeLeft + FROM Topics AS T1 + INNER JOIN Topics AS T2 + ON T2.RangeLeft + BETWEEN T1.RangeLeft + AND T1.RangeRight + AND T2.TopicID = @TopicID + ORDER BY T1.RangeLeft OPTION ( OPTIMIZE FOR ( @TopicID UNKNOWN From 3cebba4eebdd515071d2e801966b06cc82396e8d Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Wed, 1 Jul 2026 00:11:29 -0700 Subject: [PATCH 005/337] Remove errant space in test This was introduced due to an error when introducing file-level namespaces (412d8229). I need to go through and fix those. In most cases, they're just irritating. In this case, it actually breaks the test. --- OnTopic.Tests/ReverseTopicMappingServiceTest.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/OnTopic.Tests/ReverseTopicMappingServiceTest.cs b/OnTopic.Tests/ReverseTopicMappingServiceTest.cs index 629b7e89..406b9804 100644 --- a/OnTopic.Tests/ReverseTopicMappingServiceTest.cs +++ b/OnTopic.Tests/ReverseTopicMappingServiceTest.cs @@ -478,7 +478,7 @@ public async Task Map_NullProperty_MapsDefaultValue() { var target = await _mappingService.MapAsync(bindingModel); - Assert.Equal("Default page description", target?.Attributes.GetValue("MetaDescription")); + Assert.Equal("Default page description", target?.Attributes.GetValue("MetaDescription")); } From a0071d65c1f1d7d3f44ac17937ce09d94b2bbd2e Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Wed, 1 Jul 2026 20:36:32 -0700 Subject: [PATCH 006/337] Introduced new `LoadBoundaries` enum This determines what extended/related content to load, including `Children`, `Relations`, `References`, and `ExtendedAttributes`. This will be used to determine what content to dynamically load, when required. The implementation of this enum is forthcoming; this is laying the foundation. I may revisit the name later, but for now this will establish the concept. --- OnTopic/Repositories/LoadBoundaries.cs | 73 ++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 OnTopic/Repositories/LoadBoundaries.cs diff --git a/OnTopic/Repositories/LoadBoundaries.cs b/OnTopic/Repositories/LoadBoundaries.cs new file mode 100644 index 00000000..ffae3878 --- /dev/null +++ b/OnTopic/Repositories/LoadBoundaries.cs @@ -0,0 +1,73 @@ +/*============================================================================================================================== +| Author Ignia, LLC +| Client Ignia, LLC +| Project Topics Library +\=============================================================================================================================*/ + +namespace OnTopic.Repositories; + +/*============================================================================================================================== +| ENUM: LOAD BOUNDARIES +\-----------------------------------------------------------------------------------------------------------------------------*/ +/// +/// Identifies one or more deferred boundaries on a that have not yet been retrieved from the underlying +/// . Used by to specify which boundaries to ensure are loaded. +/// +[Flags] +public enum LoadBoundaries { + + /*---------------------------------------------------------------------------------------------------------------------------- + | NONE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// No boundaries are requested. Passing this value to will result in nothing + /// being loaded. + /// + None = 0, + + /*---------------------------------------------------------------------------------------------------------------------------- + | CHILDREN + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// The topic's immediate children have not been fetched. Accessing will trigger an on-demand + /// load of exactly one level. + /// + Children = 1, + + /*---------------------------------------------------------------------------------------------------------------------------- + | EXTENDED ATTRIBUTES + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// The topic's extended attributes have not been fetched. Accessing a deferred attribute on + /// will trigger an on-demand load of the entire extended attributes blob for the topic. + /// + ExtendedAttributes = 2, + + /*---------------------------------------------------------------------------------------------------------------------------- + | RELATIONSHIPS + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// The topic's relationship targets have not been fully resolved. Accessing will trigger + /// an on-demand load of all relationships associated with the topic. + /// + Relationships = 4, + + /*---------------------------------------------------------------------------------------------------------------------------- + | REFERENCES + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// The topic's reference targets have not been fully resolved. Accessing will trigger an + /// on-demand load of all references associated with the topic. + /// + References = 8, + + /*---------------------------------------------------------------------------------------------------------------------------- + | ALL + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// All four deferred boundaries. Passing this flag to ensures that every + /// deferred boundary on the topic is populated. + /// + All = Children | ExtendedAttributes | Relationships | References, + +} //Enum \ No newline at end of file From 59fa20d83772c66c687e7748427f73264462245c Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Wed, 1 Jul 2026 20:36:55 -0700 Subject: [PATCH 007/337] Introduced new `ITopicLoadResolver` interface This establishes a new interface for lazy-loading content for a given topic using the newly introduced `LoadBoundaries` flag enum (a0071d65) to establish the scope. In practice, this will be 1:1 couples with concrete `ITopicRepository` implementations, but it exposes a very narrow subset of the implementation, focused exclusively on the ability to dynamically load missing content. This lays the foundation for #111. --- OnTopic/Repositories/ITopicLoadResolver.cs | 32 ++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 OnTopic/Repositories/ITopicLoadResolver.cs diff --git a/OnTopic/Repositories/ITopicLoadResolver.cs b/OnTopic/Repositories/ITopicLoadResolver.cs new file mode 100644 index 00000000..61fc2e3b --- /dev/null +++ b/OnTopic/Repositories/ITopicLoadResolver.cs @@ -0,0 +1,32 @@ +/*============================================================================================================================== +| Author Ignia, LLC +| Client Ignia, LLC +| Project Topics Library +\=============================================================================================================================*/ + +namespace OnTopic.Repositories; + +/*============================================================================================================================== +| INTERFACE: TOPIC LOAD RESOLVER +\-----------------------------------------------------------------------------------------------------------------------------*/ +/// +/// Provides a narrow seam through which a can populate one or more deferred boundaries on demand, without +/// taking a dependency on the full . Instances are stamped onto topics by the repository as +/// they are loaded or saved; topics created in memory carry no resolver. +/// +public interface ITopicLoadResolver { + + /*============================================================================================================================ + | METHOD: ENSURE LOADED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Ensures each requested flag has been retrieved for the supplied , + /// fetching and merging whichever of them are not yet and silently skipping those already + /// loaded. Invoked by the autoloading property getters, each with its own flag. + /// + void EnsureLoaded(Topic topic, LoadBoundaries boundaries); + + /// + Task EnsureLoadedAsync(Topic topic, LoadBoundaries boundaries, CancellationToken cancellationToken = default); + +} //Interface \ No newline at end of file From e5ddc2626c0c4cd5ac698e3c28805f4682df787a Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Wed, 1 Jul 2026 21:21:05 -0700 Subject: [PATCH 008/337] Added `IsLoaded()` check to `Topic` MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Utilizing the newly introduced `LoadBoundaries` flag (a0071d65), this provides a simple check to determine if the given boundary—or, unexpectedly, boundaries—are already loaded. This offers a check so that various "boundaries" (e.g., Children, Relationships, References, &c.) can be lazy-loaded, if needed. --- OnTopic/Topic.cs | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/OnTopic/Topic.cs b/OnTopic/Topic.cs index 2bb751af..a9be8733 100644 --- a/OnTopic/Topic.cs +++ b/OnTopic/Topic.cs @@ -161,6 +161,45 @@ public Topic? Parent { /// public KeyedTopicCollection Children { get; } + /*============================================================================================================================ + | METHOD: IS LOADED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Returns if every boundary flag in has already been fetched from + /// the underlying persistence store; if any one of them are . + /// + /// + /// Reads each collection's directly without touching any autoloading getter, making it safe to + /// use in traversal and "gating" logic that should not trigger lazy-loading. + /// + /// One or more flags to test. + public bool IsLoaded(LoadBoundaries boundaries) { + + // Children + if (boundaries.HasFlag(LoadBoundaries.Children) && Children.LoadState is not LoadState.Loaded) { + return false; + } + + // Extended Attributes + if (boundaries.HasFlag(LoadBoundaries.ExtendedAttributes) && Attributes.LoadState is not LoadState.Loaded) { + return false; + } + + // Relationships + if (boundaries.HasFlag(LoadBoundaries.Relationships) && Relationships.LoadState is not LoadState.Loaded) { + return false; + } + + // References + if (boundaries.HasFlag(LoadBoundaries.References) && References.LoadState is not LoadState.Loaded) { + return false; + } + + // Unexpected + return true; + + } + /*============================================================================================================================ | PROPERTY: CONTENT TYPE \---------------------------------------------------------------------------------------------------------------------------*/ From e25f84318903252c732724f6c4c82fd59eabba8b Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Wed, 1 Jul 2026 22:06:55 -0700 Subject: [PATCH 009/337] Implement (core) `ITopicResolver` on repositories This implements the core (ready) logic from the newly introduced `ITopicResolver` (59fa20d8) to each of the `ITopicRepository` concrete implementations, including the `StubTopicRepository` used for test cases. This also relies on the (newly introduced) `IsLoaded()` (e5ddc262) on the core `Topic` entity. This doesn't (yet) include the actual "fill" processing, which is at the heart of this setup, as that will come in a subsequent commit once the underlying lazy-loading is fully implemented. This lays the foundation for #111. --- OnTopic.Data.Caching/CachedTopicRepository.cs | 63 +++++++++++++++++- OnTopic.Data.Sql/SqlTopicRepository.cs | 66 ++++++++++++++++++- OnTopic.TestDoubles/StubTopicRepository.cs | 34 +++++++++- 3 files changed, 160 insertions(+), 3 deletions(-) diff --git a/OnTopic.Data.Caching/CachedTopicRepository.cs b/OnTopic.Data.Caching/CachedTopicRepository.cs index 0efe09d0..98df1b26 100644 --- a/OnTopic.Data.Caching/CachedTopicRepository.cs +++ b/OnTopic.Data.Caching/CachedTopicRepository.cs @@ -20,7 +20,7 @@ namespace OnTopic.Data.Caching; /// for an actual data access class. /// -public class CachedTopicRepository : TopicRepositoryDecorator { +public class CachedTopicRepository : TopicRepositoryDecorator, ITopicLoadResolver { /*============================================================================================================================ | VARIABLES @@ -116,6 +116,67 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos | Return appropriate topic \-------------------------------------------------------------------------------------------------------------------------*/ return TopicRepository.Load(topicId, version, referenceTopic?? _cache); + /*============================================================================================================================ + | METHODS: TOPIC LOAD RESOLVER + \---------------------------------------------------------------------------------------------------------------------------*/ + + /// + public virtual void EnsureLoaded(Topic topic, LoadBoundaries boundaries) { + + /*-------------------------------------------------------------------------------------------------------------------------- + | Validate parameters + \-------------------------------------------------------------------------------------------------------------------------*/ + Contract.Requires(topic); + + /*-------------------------------------------------------------------------------------------------------------------------- + | Filter to pending (not yet loaded) boundaries + \-------------------------------------------------------------------------------------------------------------------------*/ + + // Children + if (topic.IsLoaded(LoadBoundaries.Children)) { + boundaries &= ~LoadBoundaries.Children; + } + + // Extended Attributes + if (topic.IsLoaded(LoadBoundaries.ExtendedAttributes)) { + boundaries &= ~LoadBoundaries.ExtendedAttributes; + } + + // None + if (boundaries is 0) { + return; + } + + } + + /// + public virtual Task EnsureLoadedAsync(Topic topic, LoadBoundaries boundaries, CancellationToken cancellationToken) { + + /*-------------------------------------------------------------------------------------------------------------------------- + | Validate parameters + \-------------------------------------------------------------------------------------------------------------------------*/ + Contract.Requires(topic); + + /*-------------------------------------------------------------------------------------------------------------------------- + | Filter to pending (i.e., not yet Loaded) boundaries + \-------------------------------------------------------------------------------------------------------------------------*/ + + // Children + if (topic.IsLoaded(LoadBoundaries.Children)) { + boundaries &= ~LoadBoundaries.Children; + } + + // Extended Attributes + if (topic.IsLoaded(LoadBoundaries.ExtendedAttributes)) { + boundaries &= ~LoadBoundaries.ExtendedAttributes; + } + + // None + if (boundaries is 0) { + return Task.CompletedTask; + } + + return Task.CompletedTask; } diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index ec397770..1081df3a 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -21,7 +21,7 @@ namespace OnTopic.Data.Sql; /// /// Concrete implementation of the class. /// -public class SqlTopicRepository : TopicRepository, ITopicRepository { +public class SqlTopicRepository : TopicRepository, ITopicRepository, ITopicLoadResolver { /*============================================================================================================================ | PRIVATE VARIABLES @@ -345,6 +345,70 @@ public override void Refresh(Topic referenceTopic, DateTime since) { } + /*============================================================================================================================ + | METHODS: TOPIC LOAD RESOLVER + \---------------------------------------------------------------------------------------------------------------------------*/ + + /// + public virtual void EnsureLoaded(Topic topic, LoadBoundaries boundaries) { + + /*-------------------------------------------------------------------------------------------------------------------------- + | Validate parameters + \-------------------------------------------------------------------------------------------------------------------------*/ + Contract.Requires(topic); + + /*-------------------------------------------------------------------------------------------------------------------------- + | Filter to pending (not yet Loaded) boundaries + \-------------------------------------------------------------------------------------------------------------------------*/ + + // Children + if (topic.IsLoaded(LoadBoundaries.Children)) { + boundaries &= ~LoadBoundaries.Children; + } + + // Extended Attributes + if (topic.IsLoaded(LoadBoundaries.ExtendedAttributes)) { + boundaries &= ~LoadBoundaries.ExtendedAttributes; + } + + // None + if (boundaries is 0) { + return; + } + + } + + /// + public virtual Task EnsureLoadedAsync(Topic topic, LoadBoundaries boundaries, CancellationToken cancellationToken) { + + /*-------------------------------------------------------------------------------------------------------------------------- + | Validate parameters + \-------------------------------------------------------------------------------------------------------------------------*/ + Contract.Requires(topic); + + /*-------------------------------------------------------------------------------------------------------------------------- + | Filter to pending (not yet Loaded) boundaries + \-------------------------------------------------------------------------------------------------------------------------*/ + + // Children + if (topic.IsLoaded(LoadBoundaries.Children)) { + boundaries &= ~LoadBoundaries.Children; + } + + // Extended Attributes + if (topic.IsLoaded(LoadBoundaries.ExtendedAttributes)) { + boundaries &= ~LoadBoundaries.ExtendedAttributes; + } + + // None + if (boundaries is 0) { + return Task.CompletedTask; + } + + return Task.CompletedTask; + + } + /*============================================================================================================================ | METHOD: SAVE \---------------------------------------------------------------------------------------------------------------------------*/ diff --git a/OnTopic.TestDoubles/StubTopicRepository.cs b/OnTopic.TestDoubles/StubTopicRepository.cs index e7fe9482..31cad18c 100644 --- a/OnTopic.TestDoubles/StubTopicRepository.cs +++ b/OnTopic.TestDoubles/StubTopicRepository.cs @@ -23,7 +23,7 @@ namespace OnTopic.TestDoubles; /// dependency on a live database or persistent data. /// [ExcludeFromCodeCoverage] -public class StubTopicRepository : TopicRepository, ITopicRepository { +public class StubTopicRepository : TopicRepository, ITopicRepository, ITopicLoadResolver { /*============================================================================================================================ | VARIABLES @@ -167,6 +167,38 @@ protected override void SaveTopic([NotNull]Topic topic, DateTime version, bool p } + /*============================================================================================================================ + | METHODS: TOPIC LOAD RESOLVER + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// + /// Stub topics always have their children fully populated in memory. For extended attributes, the boundary is promoted to + /// without merging real blob data, allowing tests to exercise the fill path without a live + /// database. + /// + /// + public virtual void EnsureLoaded(Topic topic, LoadBoundaries boundaries) { + + /*-------------------------------------------------------------------------------------------------------------------------- + | Validate parameters + \-------------------------------------------------------------------------------------------------------------------------*/ + Contract.Requires(topic); + + /*-------------------------------------------------------------------------------------------------------------------------- + | Mark extended attribute boundary as loaded; this is a no-op for children, as it's already populated in the stubs + \-------------------------------------------------------------------------------------------------------------------------*/ + if (boundaries.HasFlag(LoadBoundaries.ExtendedAttributes) && topic.Attributes.LoadState is LoadState.NotLoaded) { + topic.Attributes.LoadState = LoadState.Loaded; + } + + } + + /// + public virtual Task EnsureLoadedAsync(Topic topic, LoadBoundaries boundaries, CancellationToken cancellationToken) { + EnsureLoaded(topic, boundaries); + return Task.CompletedTask; + } + /*============================================================================================================================ | METHOD: MOVE \---------------------------------------------------------------------------------------------------------------------------*/ From 2a1ce8e5b14b45c1578f49da0267525f7abb43c1 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Wed, 1 Jul 2026 22:36:37 -0700 Subject: [PATCH 010/337] Introduce new `StampResolver()` method This introduces a new `StampResolver()` method to the base `ObservableTopicRepository` to ensure the new `ITopicResolver` implementation (59fa20d8) is available to e.g., a consuming ITopicResolver (e25f8431). This begins the implementation for #111 (and beyond). --- .../Repositories/ObservableTopicRepository.cs | 42 +++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/OnTopic/Repositories/ObservableTopicRepository.cs b/OnTopic/Repositories/ObservableTopicRepository.cs index 950d9a72..c338438d 100644 --- a/OnTopic/Repositories/ObservableTopicRepository.cs +++ b/OnTopic/Repositories/ObservableTopicRepository.cs @@ -263,6 +263,48 @@ public event EventHandler? TopicRenamed { /// public abstract void Delete(Topic topic, bool isRecursive = false); + /*============================================================================================================================ + | METHOD: STAMP RESOLVER + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Stamps the supplied and its entire loaded graph with this repository as the , enabling each topic to populate deferred portions of itself on demand. + /// + /// + /// + /// Only stamps when the current repository implements . A passthrough decorator that is + /// not itself a resolver leaves any existing inner stamp intact, rather than overwriting it. + /// + /// + /// Recursion is gated on so that unloaded branches are not force-loaded. + /// + /// + /// Call this method once on the root of a loaded or saved graph; it stamps every resident node in one pass. + /// + /// + /// The root of the topic graph to stamp. + protected void StampResolver(Topic? topic) { + + // Skip if the TopicRepository is not an ITopicLoadResolver, or if the topic doesn't exist + if (this is not ITopicLoadResolver resolver || topic is null) { + return; + } + + // Stamp the resolver on the topic + topic._resolver = resolver; + + // If the children aren't yet loaded, don't bother with them yet + if (!topic.IsLoaded(LoadBoundaries.Children)) { + return; + } + + // Stamp any children (this is recursive, obviously!) + foreach (var child in topic.Children) { + StampResolver(child); + } + + } + /*============================================================================================================================ | METHOD: NORMALIZE TO UTC \---------------------------------------------------------------------------------------------------------------------------*/ From 6cd4e80deaf3ba564f78d5a53269fe1a9f7a8a89 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Wed, 1 Jul 2026 22:41:38 -0700 Subject: [PATCH 011/337] Implement new `StampResolver()` method MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This implements the new `StampResolver()` method (2a1ce8e5) onto each of the `ITopicRepository` implementations—including base implementations like `TopicRepository` and `TopicRepositoryDecorator`—to ensure that eligible (i.e., not new) topics are able to dynamically retrieve extended attributes, relationships, references, &c. on demand, thus satisfying the prerequisites for lazy loading (#111). --- OnTopic.Data.Caching/CachedTopicRepository.cs | 12 ++++++++++- OnTopic.Data.Sql/SqlTopicRepository.cs | 10 +++++++++ OnTopic.TestDoubles/StubTopicRepository.cs | 21 +++++++++++++++++++ OnTopic/Repositories/TopicRepository.cs | 5 +++++ .../Repositories/TopicRepositoryDecorator.cs | 5 ++++- OnTopic/Topic.cs | 1 + 6 files changed, 52 insertions(+), 2 deletions(-) diff --git a/OnTopic.Data.Caching/CachedTopicRepository.cs b/OnTopic.Data.Caching/CachedTopicRepository.cs index 98df1b26..fef7a0ba 100644 --- a/OnTopic.Data.Caching/CachedTopicRepository.cs +++ b/OnTopic.Data.Caching/CachedTopicRepository.cs @@ -56,6 +56,11 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos \-------------------------------------------------------------------------------------------------------------------------*/ _cache = rootTopic; + /*-------------------------------------------------------------------------------------------------------------------------- + | Stamp resolver on loaded graph + \-------------------------------------------------------------------------------------------------------------------------*/ + StampResolver(_cache); + } /*============================================================================================================================ @@ -115,7 +120,12 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos /*-------------------------------------------------------------------------------------------------------------------------- | Return appropriate topic \-------------------------------------------------------------------------------------------------------------------------*/ - return TopicRepository.Load(topicId, version, referenceTopic?? _cache); + var topic = TopicRepository.Load(topicId, version, referenceTopic?? _cache); + StampResolver(topic); + return topic; + + } + /*============================================================================================================================ | METHODS: TOPIC LOAD RESOLVER \---------------------------------------------------------------------------------------------------------------------------*/ diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index 1081df3a..13af4456 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -170,6 +170,11 @@ public override Topic Load(int topicId, Topic? referenceTopic = null, bool isRec \-------------------------------------------------------------------------------------------------------------------------*/ base.SetContentTypeDescriptors(topic); + /*-------------------------------------------------------------------------------------------------------------------------- + | Stamp resolver + \-------------------------------------------------------------------------------------------------------------------------*/ + StampResolver(topic); + /*-------------------------------------------------------------------------------------------------------------------------- | Raise event \-------------------------------------------------------------------------------------------------------------------------*/ @@ -279,6 +284,11 @@ public override Topic Load(int topicId, DateTime version, Topic? referenceTopic topic.Attributes.Remove(attribute.Key); } + /*-------------------------------------------------------------------------------------------------------------------------- + | Stamp resolver + \-------------------------------------------------------------------------------------------------------------------------*/ + StampResolver(topic); + /*-------------------------------------------------------------------------------------------------------------------------- | Raise event \-------------------------------------------------------------------------------------------------------------------------*/ diff --git a/OnTopic.TestDoubles/StubTopicRepository.cs b/OnTopic.TestDoubles/StubTopicRepository.cs index 31cad18c..6ef85b64 100644 --- a/OnTopic.TestDoubles/StubTopicRepository.cs +++ b/OnTopic.TestDoubles/StubTopicRepository.cs @@ -58,6 +58,13 @@ public StubTopicRepository() : base() { topic = _cache.FindFirst(t => t.Id.Equals(topicId)); } + /*-------------------------------------------------------------------------------------------------------------------------- + | Stamp resolver + \-------------------------------------------------------------------------------------------------------------------------*/ + if (topic is not null) { + StampResolver(topic); + } + /*-------------------------------------------------------------------------------------------------------------------------- | Raise event \-------------------------------------------------------------------------------------------------------------------------*/ @@ -87,6 +94,13 @@ public StubTopicRepository() : base() { \-------------------------------------------------------------------------------------------------------------------------*/ var topic = _cache.GetByUniqueKey(uniqueKey); + /*-------------------------------------------------------------------------------------------------------------------------- + | Stamp resolver + \-------------------------------------------------------------------------------------------------------------------------*/ + if (topic is not null) { + StampResolver(topic); + } + /*-------------------------------------------------------------------------------------------------------------------------- | Raise event \-------------------------------------------------------------------------------------------------------------------------*/ @@ -122,6 +136,13 @@ public StubTopicRepository() : base() { topic = _cache.FindFirst(t => t.Id.Equals(topicId)); } + /*-------------------------------------------------------------------------------------------------------------------------- + | Stamp resolver + \-------------------------------------------------------------------------------------------------------------------------*/ + if (topic is not null) { + StampResolver(topic); + } + /*-------------------------------------------------------------------------------------------------------------------------- | Raise event \-------------------------------------------------------------------------------------------------------------------------*/ diff --git a/OnTopic/Repositories/TopicRepository.cs b/OnTopic/Repositories/TopicRepository.cs index f01380ec..93c8261b 100644 --- a/OnTopic/Repositories/TopicRepository.cs +++ b/OnTopic/Repositories/TopicRepository.cs @@ -303,6 +303,11 @@ public override sealed void Save([ValidatedNotNull] Topic topic, bool isRecurs ); } + /*-------------------------------------------------------------------------------------------------------------------------- + | Stamp resolver + \-------------------------------------------------------------------------------------------------------------------------*/ + StampResolver(topic); + /*-------------------------------------------------------------------------------------------------------------------------- | Raise event \-------------------------------------------------------------------------------------------------------------------------*/ diff --git a/OnTopic/Repositories/TopicRepositoryDecorator.cs b/OnTopic/Repositories/TopicRepositoryDecorator.cs index 9665d056..06eb5f0e 100644 --- a/OnTopic/Repositories/TopicRepositoryDecorator.cs +++ b/OnTopic/Repositories/TopicRepositoryDecorator.cs @@ -111,7 +111,10 @@ protected TopicRepositoryDecorator(ITopicRepository topicRepository) : base() { | METHOD: SAVE \---------------------------------------------------------------------------------------------------------------------------*/ /// - public override void Save(Topic topic, bool isRecursive = false) => TopicRepository.Save(topic, isRecursive); + public override void Save(Topic topic, bool isRecursive = false) { + TopicRepository.Save(topic, isRecursive); + StampResolver(topic); + } /*============================================================================================================================ | METHOD: MOVE diff --git a/OnTopic/Topic.cs b/OnTopic/Topic.cs index a9be8733..dea0de45 100644 --- a/OnTopic/Topic.cs +++ b/OnTopic/Topic.cs @@ -30,6 +30,7 @@ public class Topic: ITrackDirtyKeys { private string? _originalKey; private Topic? _parent; readonly DirtyKeyCollection _dirtyKeys = new(); + internal ITopicLoadResolver? _resolver; /*============================================================================================================================ | CONSTRUCTOR From 9df2db70ac08ca9380b165fb58c66f4ad63452ee Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Wed, 1 Jul 2026 23:13:57 -0700 Subject: [PATCH 012/337] Implemented `EnsureLoaded[Async]()` on `Topic` Call into the newly introduced `EnsureLoaded()` (e25f8431) methods determined by the new `ITopicLoadResolver` on each of the concrete `ITopicRepository` implementations (59fa20d8). This is a core component of #111. --- OnTopic/Topic.cs | 111 ++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 110 insertions(+), 1 deletion(-) diff --git a/OnTopic/Topic.cs b/OnTopic/Topic.cs index dea0de45..117b3da2 100644 --- a/OnTopic/Topic.cs +++ b/OnTopic/Topic.cs @@ -6,10 +6,11 @@ using System.Collections.ObjectModel; using System.Diagnostics.CodeAnalysis; using System.Globalization; +using OnTopic.Associations; using OnTopic.Collections; using OnTopic.Collections.Specialized; using OnTopic.Metadata; -using OnTopic.Associations; +using OnTopic.Repositories; namespace OnTopic; @@ -201,6 +202,114 @@ public bool IsLoaded(LoadBoundaries boundaries) { } + /*============================================================================================================================ + | METHODS: ENSURE LOADED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Ensures each requested flag has been retrieved, while fetching and merging whichever of + /// them are not yet , and silently skipping those already are. Returns immediately if the + /// resolver is absent or the topic is new. + /// + /// + /// The synchronous form backs the autoloading property getters (e.g., the getter); the asynchronous + /// form is for callers, such as a mapping or navigation service, that need to prepopulate one or more boundaries before + /// accessing them, thus avoiding a synchronous block on a "cold" node. A flag call lets those callers request everything a + /// node's mapping needs in a single round trip. + /// + /// + /// One or more flags identifying the boundaries that should be ensured to be loaded. + /// + public void EnsureLoaded(LoadBoundaries boundaries) { + + /*-------------------------------------------------------------------------------------------------------------------------- + | Skip for obvious reasons + \-------------------------------------------------------------------------------------------------------------------------*/ + if (_resolver is null || IsNew) { + return; + } + + /*-------------------------------------------------------------------------------------------------------------------------- + | Filter to boundaries that are not yet loaded + \-------------------------------------------------------------------------------------------------------------------------*/ + + // Children + if (IsLoaded(LoadBoundaries.Children)) { + boundaries &= ~LoadBoundaries.Children; + } + + // ExtendedAttributes + if (IsLoaded(LoadBoundaries.ExtendedAttributes)) { + boundaries &= ~LoadBoundaries.ExtendedAttributes; + } + + // Relationships + if (IsLoaded(LoadBoundaries.Relationships)) { + boundaries &= ~LoadBoundaries.Relationships; + } + + // References + if (IsLoaded(LoadBoundaries.References)) { + boundaries &= ~LoadBoundaries.References; + } + + // None + if (boundaries is LoadBoundaries.None) { + return; + } + + // Ensure the appropriate boundaries are loaded + _resolver.EnsureLoaded(this, boundaries); + + } + + /// + /// + /// One or more flags identifying the boundaries that should be ensured to be loaded. + /// + /// An optional token that can be used to cancel the operation. + public Task EnsureLoadedAsync(LoadBoundaries boundaries, CancellationToken cancellationToken = default) { + + /*-------------------------------------------------------------------------------------------------------------------------- + | Skip for obvious reasons + \-------------------------------------------------------------------------------------------------------------------------*/ + if (_resolver is null || IsNew) { + return Task.CompletedTask; + } + + /*-------------------------------------------------------------------------------------------------------------------------- + | Filter to boundaries that are not yet loaded + \-------------------------------------------------------------------------------------------------------------------------*/ + + // Children + if (IsLoaded(LoadBoundaries.Children)) { + boundaries &= ~LoadBoundaries.Children; + } + + // Extended Attributes + if (IsLoaded(LoadBoundaries.ExtendedAttributes)) { + boundaries &= ~LoadBoundaries.ExtendedAttributes; + } + + // Relationships + if (IsLoaded(LoadBoundaries.Relationships)) { + boundaries &= ~LoadBoundaries.Relationships; + } + + // References + if (IsLoaded(LoadBoundaries.References)) { + boundaries &= ~LoadBoundaries.References; + } + + // None + if (boundaries is LoadBoundaries.None) { + return Task.CompletedTask; + } + + // Ensure the appropriate boundaries are loaded + return _resolver.EnsureLoadedAsync(this, boundaries, cancellationToken); + + } + /*============================================================================================================================ | PROPERTY: CONTENT TYPE \---------------------------------------------------------------------------------------------------------------------------*/ From dedb2af68393cd8b6dbe3e09871b75455ffe4ba3 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Wed, 1 Jul 2026 23:36:30 -0700 Subject: [PATCH 013/337] Established unit tests for `ITopicLoadResolver` This establishes multiple xUnit tests against the new `ITopicLoadResolver` (59fa20d8, e25f8431), `EnsureLoaded[Async]()` (9df2db70), and `StampResolver()` (6cd4e80d) implementations. This also introduces the `TrackingResolver` test double for the use in the `TopicTest`'s `EnsureLoaded_IsNew_DoesNotInvokeResolver()` test, though I also suspect it'll have wider (reusability) benefits in the future. --- .../TestDoubles/TrackingTopicLoadResolver.cs | 47 ++++++++++++++ OnTopic.Tests/TopicRepositoryBaseTest.cs | 61 +++++++++++++++++++ OnTopic.Tests/TopicTest.cs | 49 ++++++++++++++- 3 files changed, 156 insertions(+), 1 deletion(-) create mode 100644 OnTopic.Tests/TestDoubles/TrackingTopicLoadResolver.cs diff --git a/OnTopic.Tests/TestDoubles/TrackingTopicLoadResolver.cs b/OnTopic.Tests/TestDoubles/TrackingTopicLoadResolver.cs new file mode 100644 index 00000000..e23ef087 --- /dev/null +++ b/OnTopic.Tests/TestDoubles/TrackingTopicLoadResolver.cs @@ -0,0 +1,47 @@ +/*============================================================================================================================== +| Author Ignia, LLC +| Client Ignia, LLC +| Project Topics Library +\=============================================================================================================================*/ +using OnTopic.Repositories; + +namespace OnTopic.Tests.TestDoubles; + +/*============================================================================================================================== +| CLASS: TRACKING TOPIC LOAD RESOLVER +\-----------------------------------------------------------------------------------------------------------------------------*/ +/// +/// A minimal spy that records whether it was invoked, without performing any actual loading. +/// +[ExcludeFromCodeCoverage] +internal sealed class TrackingTopicLoadResolver : ITopicLoadResolver { + + /*============================================================================================================================ + | PROPERTY: WAS CALLED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Returns if either or was invoked. + /// + public bool WasCalled { get; private set; } + + /*============================================================================================================================ + | METHOD: ENSURE LOADED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + void ITopicLoadResolver.EnsureLoaded(Topic topic, LoadBoundaries boundaries) => WasCalled = true; + + /*============================================================================================================================ + | METHOD: ENSURE LOADED (ASYNC) + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + Task ITopicLoadResolver.EnsureLoadedAsync( + Topic topic, + LoadBoundaries boundaries, + CancellationToken cancellationToken + ) { + WasCalled = true; + return Task.CompletedTask; + } + +} //Class diff --git a/OnTopic.Tests/TopicRepositoryBaseTest.cs b/OnTopic.Tests/TopicRepositoryBaseTest.cs index efa9b764..21315c7d 100644 --- a/OnTopic.Tests/TopicRepositoryBaseTest.cs +++ b/OnTopic.Tests/TopicRepositoryBaseTest.cs @@ -1100,6 +1100,67 @@ public void Save_TopicMovedEvent_IsRaised() { } + /*============================================================================================================================ + | TEST: SAVE: NEW TOPIC: STAMPS RESOLVER + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Saves a new and confirms that the repository stamps a onto it so + /// that deferred boundaries can be populated on demand after the save. + /// + [Fact] + public void Save_NewTopic_StampsResolver() { + + var parent = _topicRepository.Load("Root:Web:Web_3:Web_3_0"); + var topic = new Topic("Test", "Page", parent); + + _topicRepository.Save(topic); + + Assert.NotNull(topic._resolver); + + } + + /*============================================================================================================================ + | TEST: ENSURE LOADED: EXTENDED ATTRIBUTES NOT LOADED: MARKS LOADED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Loads a whose extended-attribute boundary has been manually set to + /// and confirms that promotes the boundary to via the 's fill. + /// + [Fact] + public void EnsureLoaded_ExtendedAttributesNotLoaded_MarksLoaded() { + + var topic = _topicRepository.Load(11111); + + topic!.Attributes.LoadState = LoadState.NotLoaded; + topic.EnsureLoaded(LoadBoundaries.ExtendedAttributes); + + Assert.True(topic.IsLoaded(LoadBoundaries.ExtendedAttributes)); + + } + + /*============================================================================================================================ + | TEST: ENSURE LOADED: MIXED BOUNDARIES: SKIPS LOADED BOUNDARIES + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Calls with a mixed set of flags, including one already set to and one , and confirms that only the pending boundary is + /// forwarded to the resolver, leaving the already-loaded boundary unchanged. + /// + [Fact] + public void EnsureLoaded_MixedBoundaries_SkipsLoadedBoundaries() { + + var topic = _topicRepository.Load(11111); + + topic!.Attributes.LoadState = LoadState.NotLoaded; + Assert.True(topic.IsLoaded(LoadBoundaries.Children)); + topic.EnsureLoaded(LoadBoundaries.Children | LoadBoundaries.ExtendedAttributes); + + Assert.True(topic.IsLoaded(LoadBoundaries.ExtendedAttributes)); + Assert.True(topic.IsLoaded(LoadBoundaries.Children)); + + } + /*============================================================================================================================ | TEST: MOVE: TOPIC MOVED EVENT: IS RAISED \---------------------------------------------------------------------------------------------------------------------------*/ diff --git a/OnTopic.Tests/TopicTest.cs b/OnTopic.Tests/TopicTest.cs index 0340cda3..1bc17193 100644 --- a/OnTopic.Tests/TopicTest.cs +++ b/OnTopic.Tests/TopicTest.cs @@ -6,6 +6,7 @@ using OnTopic.Collections; using OnTopic.Metadata; using OnTopic.Repositories; +using OnTopic.Tests.TestDoubles; using Xunit; namespace OnTopic.Tests; @@ -520,7 +521,6 @@ public void MarkClean_NewTopic_RemainsDirty() { var topic = new Topic("Topic", "Page"); topic.Attributes.SetValue("Attribute", "Test"); - topic.MarkClean("Attribute", true); topic.MarkClean(true); @@ -529,4 +529,51 @@ public void MarkClean_NewTopic_RemainsDirty() { } + /*============================================================================================================================ + | TEST: ENSURE LOADED: NULL RESOLVER: DOES NOT THROW + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Calls on an in-memory topic with no resolver and confirms it completes + /// without throwing. + /// + [Fact] + public void EnsureLoaded_NullResolver_DoesNotThrow() { + var topic = new Topic("Topic", "Page"); + topic.EnsureLoaded(LoadBoundaries.All); + } + + /*============================================================================================================================ + | TEST: ENSURE LOADED: IS NEW: DOES NOT INVOKE RESOLVER + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Calls on a new topic (no ) that has a resolver + /// stamped on it and confirms the resolver is not invoked. + /// + /// + /// A new topic may carry a resolver if it was created as a child of a loaded node; it must not trigger a fill until it has + /// been persisted and has a stable . + /// + [Fact] + public void EnsureLoaded_IsNew_DoesNotInvokeResolver() { + + /*-------------------------------------------------------------------------------------------------------------------------- + | Establish variables + \-------------------------------------------------------------------------------------------------------------------------*/ + var topic = new Topic("Topic", "Page"); // Id = -1 → IsNew = true + + /*-------------------------------------------------------------------------------------------------------------------------- + | Establish tracking resolver + \-------------------------------------------------------------------------------------------------------------------------*/ + var tracker = new TrackingTopicLoadResolver(); + topic._resolver = tracker; + topic.Children.LoadState = LoadState.NotLoaded; + + /*-------------------------------------------------------------------------------------------------------------------------- + | Verify resolver is not called + \-------------------------------------------------------------------------------------------------------------------------*/ + topic.EnsureLoaded(LoadBoundaries.Children); + Assert.False(tracker.WasCalled); + + } + } //Class \ No newline at end of file From 9e712ffb1d684834f50881e5dc12fb6c8aa5ac6e Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Wed, 1 Jul 2026 23:44:47 -0700 Subject: [PATCH 014/337] Intercept `GetValue()` for lazy-loading attributes This ensures that when the `AttributeCollection`'s `LoadState` is `NotLoaded` that extended attributes are loaded from the new `EnsureLoaded()` implementation (9df2db70), thus fulfilling the requirement of lazy-loading extended attributes (per #111). --- OnTopic/Attributes/AttributeCollection.cs | 27 +++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/OnTopic/Attributes/AttributeCollection.cs b/OnTopic/Attributes/AttributeCollection.cs index 65b2ef08..121eac3b 100644 --- a/OnTopic/Attributes/AttributeCollection.cs +++ b/OnTopic/Attributes/AttributeCollection.cs @@ -3,6 +3,7 @@ | Client Ignia, LLC | Project Topics Library \=============================================================================================================================*/ +using System.Diagnostics.CodeAnalysis; using OnTopic.Collections.Specialized; using OnTopic.Repositories; @@ -97,6 +98,32 @@ public bool IsDirty(bool excludeLastModified) (!excludeLastModified || !a.Key.StartsWith("LastModified", StringComparison.OrdinalIgnoreCase)) ); + /*============================================================================================================================ + | METHOD: GET VALUE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Retrieves the value associated with the specified , autoloading the extended-attribute blob if the + /// key is not yet loaded and the extended-attribute boundary is . + /// + /// + /// Indexed attributes are always loaded in the local collection; the autoload is skipped for them. A deferred key that has + /// never been fetched triggers a single synchronous blob fill through the stamped resolver; all subsequent reads find the + /// boundary and return immediately without an additional round-trip. + /// + /// The string identifier for the . + /// A string value to which to fall back in the case the value is not found. + /// + /// Determines if the value should be inherited from the parent topic when not found locally. + /// + /// The maximum number of ancestor hops when inheriting from parent topics. + [return: NotNullIfNotNull(nameof(defaultValue))] + internal override string? GetValue(string key, string? defaultValue, bool inheritFromParent, int maxHops) { + if (LoadState is LoadState.NotLoaded && !Contains(key)) { + AssociatedTopic.EnsureLoaded(LoadBoundaries.ExtendedAttributes); + } + return base.GetValue(key, defaultValue, inheritFromParent, maxHops); + } + /*============================================================================================================================ | METHOD: SET VALUE \---------------------------------------------------------------------------------------------------------------------------*/ From 8c2c81dabf7a320ecaefc7f0c47de752a3e1428b Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Thu, 2 Jul 2026 15:56:10 -0700 Subject: [PATCH 015/337] Extend `GetTopics` sproc w/ conditionally loading This extends the `GetTopics` stored procedure to include a series of `@Include` which map to the new `LoadBoundaries` enum (a0071d65) as well as `@Load` parameters, which will map to a forthcoming `LoadScope` enum. This is a breaking change, and will be deployed as part of OnTopic 6.0.0, as with the rest of the changes in development. --- .../Stored Procedures/GetTopics.sql | 37 ++++++++++++++++--- 1 file changed, 32 insertions(+), 5 deletions(-) diff --git a/OnTopic.Data.Sql.Database/Stored Procedures/GetTopics.sql b/OnTopic.Data.Sql.Database/Stored Procedures/GetTopics.sql index fdfcc699..1836e536 100644 --- a/OnTopic.Data.Sql.Database/Stored Procedures/GetTopics.sql +++ b/OnTopic.Data.Sql.Database/Stored Procedures/GetTopics.sql @@ -6,8 +6,14 @@ -------------------------------------------------------------------------------------------------------------------------------- CREATE PROCEDURE [dbo].[GetTopics] - @TopicID INT = -1, - @DeepLoad BIT = 1, + @TopicID INT = -1, + @LoadDescendants BIT = 1, + @LoadAscendants BIT = 0, + @IncludeIndexed BIT = 1, + @IncludeExtended BIT = 1, + @IncludeRelationships BIT = 1, + @IncludeReferences BIT = 1, + @IncludeHistory BIT = 1, @UniqueKey NVARCHAR(255) = NULL AS @@ -42,7 +48,7 @@ CLUSTERED INDEX IX_C_Topics_TopicID -------------------------------------------------------------------------------------------------------------------------------- -- SELECT TOPIC AND DESCENDENTS -------------------------------------------------------------------------------------------------------------------------------- -IF @DeepLoad = 1 +IF @LoadDescendants = 1 BEGIN INSERT #Topics ( TopicID, @@ -70,7 +76,7 @@ IF @DeepLoad = 1 -- Ancestors are rows whose nested-set range contains the requested node's RangeLeft, i.e., the mirror of the descendant query -- above. This guarantees the full parent chain is always materialized, even on a shallow (non-recursive) load. -------------------------------------------------------------------------------------------------------------------------------- -ELSE +ELSE IF @LoadAscendants = 1 BEGIN INSERT #Topics ( TopicID, @@ -92,6 +98,22 @@ ELSE ) END +-------------------------------------------------------------------------------------------------------------------------------- +-- SELECT SINGLE TOPIC (NO SCOPE) +-------------------------------------------------------------------------------------------------------------------------------- +-- Inserts only the requested topic; used by the lazy-load resolver to fill a single topic's extended attributes without +-- traversing the tree in either direction. +-------------------------------------------------------------------------------------------------------------------------------- +ELSE + BEGIN + INSERT #Topics ( + TopicID, + SortOrder + ) + SELECT @TopicID, + 0 + END + -------------------------------------------------------------------------------------------------------------------------------- -- SELECT KEY ATTRIBUTES -------------------------------------------------------------------------------------------------------------------------------- @@ -115,6 +137,7 @@ SELECT Attributes.TopicID, FROM AttributeIndex AS Attributes JOIN #Topics AS Storage ON Storage.TopicID = Attributes.TopicID +WHERE @IncludeIndexed = 1 -------------------------------------------------------------------------------------------------------------------------------- -- SELECT EXTENDED ATTRIBUTES @@ -125,6 +148,7 @@ SELECT Attributes.TopicID, FROM ExtendedAttributeIndex AS Attributes JOIN #Topics AS Storage ON Storage.TopicID = Attributes.TopicID +WHERE @IncludeExtended = 1 -------------------------------------------------------------------------------------------------------------------------------- -- SELECT RELATIONSHIPS @@ -136,6 +160,7 @@ SELECT Source_TopicID, FROM RelationshipIndex AS Relationships JOIN #Topics AS Storage ON Storage.TopicID = Relationships.Source_TopicID +WHERE @IncludeRelationships = 1 -------------------------------------------------------------------------------------------------------------------------------- -- SELECT REFERENCES @@ -146,6 +171,7 @@ SELECT Source_TopicID, FROM ReferenceIndex AS TopicReferences JOIN #Topics AS Storage ON Storage.TopicID = TopicReferences.Source_TopicID +WHERE @IncludeReferences = 1 -------------------------------------------------------------------------------------------------------------------------------- -- SELECT HISTORY @@ -154,4 +180,5 @@ SELECT History.TopicID, Version FROM VersionHistoryIndex AS History JOIN #Topics AS Storage - ON Storage.TopicID = History.TopicID; \ No newline at end of file + ON Storage.TopicID = History.TopicID +WHERE @IncludeHistory = 1; \ No newline at end of file From de60afb45186fd41d824d85a608a967d34706564 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Thu, 2 Jul 2026 17:16:43 -0700 Subject: [PATCH 016/337] Added new `GetTopics` parameters to repository Wired up the new `GetTopics` stored procedure parameters (8c2c81da) to the `LoadBoundaries` enum (a0071d65) within the `EnsureLoaded()` and `EnsureLoadedAsync()` methods (e25f8431). --- OnTopic.Data.Sql/SqlTopicRepository.cs | 206 ++++++++++++++++++++++++- 1 file changed, 202 insertions(+), 4 deletions(-) diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index 13af4456..b729b603 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -6,6 +6,7 @@ using System.Diagnostics.CodeAnalysis; using System.Globalization; using System.Text; +using OnTopic.Collections.Specialized; using OnTopic.Data.Sql.Models; using OnTopic.Querying; using OnTopic.Repositories; @@ -130,7 +131,8 @@ public override Topic Load(int topicId, Topic? referenceTopic = null, bool isRec | Establish query parameters \-------------------------------------------------------------------------------------------------------------------------*/ command.AddParameter("TopicID", topicId); - command.AddParameter("DeepLoad", isRecursive); + command.AddParameter("LoadDescendants", isRecursive); + command.AddParameter("LoadAscendants", !isRecursive); /*-------------------------------------------------------------------------------------------------------------------------- | Process database query @@ -367,6 +369,13 @@ public virtual void EnsureLoaded(Topic topic, LoadBoundaries boundaries) { \-------------------------------------------------------------------------------------------------------------------------*/ Contract.Requires(topic); + /*-------------------------------------------------------------------------------------------------------------------------- + | Skip for new topics, as there's no persistent data to fetch + \-------------------------------------------------------------------------------------------------------------------------*/ + if (topic.IsNew) { + return; + } + /*-------------------------------------------------------------------------------------------------------------------------- | Filter to pending (not yet Loaded) boundaries \-------------------------------------------------------------------------------------------------------------------------*/ @@ -386,16 +395,87 @@ public virtual void EnsureLoaded(Topic topic, LoadBoundaries boundaries) { return; } + /*-------------------------------------------------------------------------------------------------------------------------- + | Children not yet implemented; guard before opening a connection + \-------------------------------------------------------------------------------------------------------------------------*/ + if (boundaries.HasFlag(LoadBoundaries.Children)) { + throw new NotImplementedException("Per-level child loading will be implemented in Task 5."); + } + + /*-------------------------------------------------------------------------------------------------------------------------- + | Establish database connection + \-------------------------------------------------------------------------------------------------------------------------*/ + using var connection = new SqlConnection(_connectionString); + using var command = new SqlCommand("GetTopics", connection) { + CommandType = CommandType.StoredProcedure + }; + + // Set the stored procedure parameters based on the LoadBoundaries enum values + AddEnsureLoadedParameters(command, topic.Id, boundaries); + + /*-------------------------------------------------------------------------------------------------------------------------- + | Process database query + \-------------------------------------------------------------------------------------------------------------------------*/ + try { + + // Setup + connection.Open(); + var topics = new TopicIndex { [topic.Id] = topic }; + using var reader = command.ExecuteReader(); + + // Skip key-attributes result set; these were populated when the topic was first loaded + reader.NextResult(); + + // Indexed attributes (will be populated when Children boundary is implemented) + while (reader.Read()) { + + } + + // Extended attributes + reader.NextResult(); + while (reader.Read()) { + reader.SetExtendedAttributes(topics, markDirty: false, preserveDirtyKeys: true); + } + + // Relationships + reader.NextResult(); + while (reader.Read()) { + reader.SetRelationships(topics, markDirty: false); + } + + // References + reader.NextResult(); + while (reader.Read()) { + reader.SetReferences(topics, markDirty: false); + } + + } + catch (SqlException exception) { + throw new TopicRepositoryException($"Topic boundaries failed to load: '{exception.Message}'", exception); + } + + /*-------------------------------------------------------------------------------------------------------------------------- + | Mark loaded boundaries as confirmed + \-------------------------------------------------------------------------------------------------------------------------*/ + MarkBoundariesLoaded(topic, boundaries); + } /// - public virtual Task EnsureLoadedAsync(Topic topic, LoadBoundaries boundaries, CancellationToken cancellationToken) { + public virtual async Task EnsureLoadedAsync(Topic topic, LoadBoundaries boundaries, CancellationToken cancellationToken) { /*-------------------------------------------------------------------------------------------------------------------------- | Validate parameters \-------------------------------------------------------------------------------------------------------------------------*/ Contract.Requires(topic); + /*-------------------------------------------------------------------------------------------------------------------------- + | Skip for new topics, as there's no persistent data to fetch + \-------------------------------------------------------------------------------------------------------------------------*/ + if (topic.IsNew) { + return; + } + /*-------------------------------------------------------------------------------------------------------------------------- | Filter to pending (not yet Loaded) boundaries \-------------------------------------------------------------------------------------------------------------------------*/ @@ -412,10 +492,72 @@ public virtual Task EnsureLoadedAsync(Topic topic, LoadBoundaries boundaries, Ca // None if (boundaries is 0) { - return Task.CompletedTask; + return; } - return Task.CompletedTask; + /*-------------------------------------------------------------------------------------------------------------------------- + | Children not yet implemented; guard before opening a connection + \-------------------------------------------------------------------------------------------------------------------------*/ + if (boundaries.HasFlag(LoadBoundaries.Children)) { + throw new NotImplementedException("Per-level child loading will be implemented in Task 5."); + } + + /*-------------------------------------------------------------------------------------------------------------------------- + | Establish database connection + \-------------------------------------------------------------------------------------------------------------------------*/ + using var connection = new SqlConnection(_connectionString); + using var command = new SqlCommand("GetTopics", connection) { + CommandType = CommandType.StoredProcedure + }; + + // Set the stored procedure parameters based on the LoadBoundaries enum values + AddEnsureLoadedParameters(command, topic.Id, boundaries); + + /*-------------------------------------------------------------------------------------------------------------------------- + | Process database query + \-------------------------------------------------------------------------------------------------------------------------*/ + try { + + // Setup + await connection.OpenAsync(cancellationToken).ConfigureAwait(false); + var topics = new TopicIndex { [topic.Id] = topic }; + using var reader = (SqlDataReader)await command.ExecuteReaderAsync(cancellationToken).ConfigureAwait(false); + + // Skip key-attributes result set; these were populated when the topic was first loaded + await reader.NextResultAsync(cancellationToken).ConfigureAwait(false); + + // Indexed attributes (will be populated when Children boundary is implemented) + while (await reader.ReadAsync(cancellationToken).ConfigureAwait(false)) { + + } + + // Extended attributes + await reader.NextResultAsync(cancellationToken).ConfigureAwait(false); + while (await reader.ReadAsync(cancellationToken).ConfigureAwait(false)) { + reader.SetExtendedAttributes(topics, markDirty: false, preserveDirtyKeys: true); + } + + // Relationships + await reader.NextResultAsync(cancellationToken).ConfigureAwait(false); + while (await reader.ReadAsync(cancellationToken).ConfigureAwait(false)) { + reader.SetRelationships(topics, markDirty: false); + } + + // References + await reader.NextResultAsync(cancellationToken).ConfigureAwait(false); + while (await reader.ReadAsync(cancellationToken).ConfigureAwait(false)) { + reader.SetReferences(topics, markDirty: false); + } + + } + catch (SqlException exception) { + throw new TopicRepositoryException($"Topic boundaries failed to load: '{exception.Message}'", exception); + } + + /*-------------------------------------------------------------------------------------------------------------------------- + | Mark loaded boundaries as confirmed + \-------------------------------------------------------------------------------------------------------------------------*/ + MarkBoundariesLoaded(topic, boundaries); } @@ -689,6 +831,62 @@ protected override sealed void DeleteTopic(Topic topic) { } + /*============================================================================================================================ + | METHOD: MARK BOUNDARIES LOADED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Marks each boundary in as on the given + /// after a successful resolver fill. + /// + private static void MarkBoundariesLoaded(Topic topic, LoadBoundaries boundaries) { + + // Extended attributes + if (boundaries.HasFlag(LoadBoundaries.ExtendedAttributes)) { + topic.Attributes.LoadState = LoadState.Loaded; + } + + // Relationships + if (boundaries.HasFlag(LoadBoundaries.Relationships)) { + topic.Relationships.LoadState = LoadState.Loaded; + } + + // References + if (boundaries.HasFlag(LoadBoundaries.References)) { + topic.References.LoadState = LoadState.Loaded; + } + + } + + /*============================================================================================================================ + | METHOD: ADD ENSURE LOADED PARAMETERS + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Configures a targeting GetTopics for use by the , + /// setting the payload parameters based on the requested . + /// + /// + /// Scope is always None (i.e., a single node) for resolver fills, as the caller is already in the graph. History + /// is never a lazy-load boundary and so is always excluded. Indexed attributes are only requested when filling the boundary. + /// + private static void AddEnsureLoadedParameters(SqlCommand command, int topicId, LoadBoundaries boundaries) { + + // Set the topic we're working with + command.AddParameter("TopicID", topicId); + + // Scope: Always None (i.e., single node) for resolver fills + command.AddParameter("LoadDescendants", false); + command.AddParameter("LoadAscendants", false); + + // Payload: Include only what the requested boundaries require + command.AddParameter("IncludeIndexed", boundaries.HasFlag(LoadBoundaries.Children)); + command.AddParameter("IncludeExtended", boundaries.HasFlag(LoadBoundaries.ExtendedAttributes)); + command.AddParameter("IncludeRelationships", boundaries.HasFlag(LoadBoundaries.Relationships)); + command.AddParameter("IncludeReferences", boundaries.HasFlag(LoadBoundaries.References)); + command.AddParameter("IncludeHistory", false); + + } + /*============================================================================================================================ | METHOD: PERSIST RELATIONSHIPS \---------------------------------------------------------------------------------------------------------------------------*/ From 5e9379064c996ed3b97fc4fc358abef9d6021f6a Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Thu, 2 Jul 2026 17:19:21 -0700 Subject: [PATCH 017/337] Added modified `GetTopics` parameters to SQL test This updates the `StoredProcedures.resx` SQL test to use `@LoadDesceendants` instead of `@DeepLoad`, as per the recent change to the `GetTopics` stored procedure (8c2c81da). This will later need to be updated to have additional tests to evaluate all of the parameters. --- OnTopic.Data.Sql.Database.Tests/StoredProcedures.resx | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/OnTopic.Data.Sql.Database.Tests/StoredProcedures.resx b/OnTopic.Data.Sql.Database.Tests/StoredProcedures.resx index b3f95e0f..5e8497f0 100644 --- a/OnTopic.Data.Sql.Database.Tests/StoredProcedures.resx +++ b/OnTopic.Data.Sql.Database.Tests/StoredProcedures.resx @@ -234,14 +234,12 @@ EXECUTE [dbo].[GetTopicVersion] -- ESTABLISH VARIABLES -------------------------------------------------------------------------------------------------------------------------------- DECLARE @TopicID AS INT, - @DeepLoad AS BIT, @UniqueKey AS NVARCHAR (255); -------------------------------------------------------------------------------------------------------------------------------- -- SET VARIABLES -------------------------------------------------------------------------------------------------------------------------------- -SELECT @DeepLoad = 1, - @UniqueKey = 'GetTopicsTest'; +SELECT @UniqueKey = 'GetTopicsTest'; SELECT @TopicID = TopicID FROM Topics @@ -251,9 +249,8 @@ WHERE TopicKey = @UniqueKey -- EXECUTE PROCEDURE -------------------------------------------------------------------------------------------------------------------------------- EXECUTE [dbo].[GetTopics] - @TopicID, - @DeepLoad, - NULL; + @TopicID = @TopicID, + @LoadDescendants = 1; -------------------------------------------------------------------------------------------------------------------------------- From 31b986a8bd8ac975f2ccd009fd924f07706a91ed Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Thu, 2 Jul 2026 17:31:37 -0700 Subject: [PATCH 018/337] Centralized, extended, optimized boundary filters The boundary filters have been centralized into the `FilterLoadedBoundaries()` private method, extended to support `Relationships` and `References`, and optimized to use a loop instead of defining each one individually. --- OnTopic.Data.Sql/SqlTopicRepository.cs | 59 +++++++++++++++----------- 1 file changed, 34 insertions(+), 25 deletions(-) diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index b729b603..ba0fb223 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -379,18 +379,8 @@ public virtual void EnsureLoaded(Topic topic, LoadBoundaries boundaries) { /*-------------------------------------------------------------------------------------------------------------------------- | Filter to pending (not yet Loaded) boundaries \-------------------------------------------------------------------------------------------------------------------------*/ + boundaries = FilterLoadedBoundaries(topic, boundaries); - // Children - if (topic.IsLoaded(LoadBoundaries.Children)) { - boundaries &= ~LoadBoundaries.Children; - } - - // Extended Attributes - if (topic.IsLoaded(LoadBoundaries.ExtendedAttributes)) { - boundaries &= ~LoadBoundaries.ExtendedAttributes; - } - - // None if (boundaries is 0) { return; } @@ -405,9 +395,9 @@ public virtual void EnsureLoaded(Topic topic, LoadBoundaries boundaries) { /*-------------------------------------------------------------------------------------------------------------------------- | Establish database connection \-------------------------------------------------------------------------------------------------------------------------*/ - using var connection = new SqlConnection(_connectionString); - using var command = new SqlCommand("GetTopics", connection) { - CommandType = CommandType.StoredProcedure + using var connection = new SqlConnection(_connectionString); + using var command = new SqlCommand("GetTopics", connection) { + CommandType = CommandType.StoredProcedure }; // Set the stored procedure parameters based on the LoadBoundaries enum values @@ -479,18 +469,8 @@ public virtual async Task EnsureLoadedAsync(Topic topic, LoadBoundaries boundari /*-------------------------------------------------------------------------------------------------------------------------- | Filter to pending (not yet Loaded) boundaries \-------------------------------------------------------------------------------------------------------------------------*/ + boundaries = FilterLoadedBoundaries(topic, boundaries); - // Children - if (topic.IsLoaded(LoadBoundaries.Children)) { - boundaries &= ~LoadBoundaries.Children; - } - - // Extended Attributes - if (topic.IsLoaded(LoadBoundaries.ExtendedAttributes)) { - boundaries &= ~LoadBoundaries.ExtendedAttributes; - } - - // None if (boundaries is 0) { return; } @@ -887,6 +867,35 @@ private static void AddEnsureLoadedParameters(SqlCommand command, int topicId, L } + /*============================================================================================================================ + | METHOD: FILTER LOADED BOUNDARIES + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Returns with any already- flags cleared, so that and skip redundant round-trips. + /// + private static LoadBoundaries FilterLoadedBoundaries(Topic topic, LoadBoundaries boundaries) { + + // Loop through all boundaries + foreach (LoadBoundaries flag in Enum.GetValues()) { + + // Skip None (0) and All (composite) + if (flag is LoadBoundaries.None or LoadBoundaries.All) { + continue; + } + + // Strip the boundary if is is already fully loaded + if (topic.IsLoaded(flag)) { + boundaries &= ~flag; + } + + } + + // Return filtered boundaries + return boundaries; + + } + /*============================================================================================================================ | METHOD: PERSIST RELATIONSHIPS \---------------------------------------------------------------------------------------------------------------------------*/ From 9e27887e94f8e7a6a5a253b5e8ae9acd8fbeae03 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Thu, 2 Jul 2026 17:43:09 -0700 Subject: [PATCH 019/337] Added `preservedDirty` parameter This is set to true when lazy-loading extended attributes so that any existing dirty extended attributes aren't overwritten in memory by the persisted data. I also set the `SetExtendedAttributes()`, `SetRelationships()`, and `SetReferences()` to `internal` since they're now used by the `EnsureLoaded()` method on the `SqlTopicRepository` (de60afb4). (This all should have been done on or prior to that commit; whoops. --- OnTopic.Data.Sql/SqlTopicRepository.cs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index ba0fb223..b4b1c8a1 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -424,7 +424,7 @@ public virtual void EnsureLoaded(Topic topic, LoadBoundaries boundaries) { // Extended attributes reader.NextResult(); while (reader.Read()) { - reader.SetExtendedAttributes(topics, markDirty: false, preserveDirtyKeys: true); + reader.SetExtendedAttributes(topics, markDirty: false, preserveDirty: true); } // Relationships @@ -514,7 +514,7 @@ public virtual async Task EnsureLoadedAsync(Topic topic, LoadBoundaries boundari // Extended attributes await reader.NextResultAsync(cancellationToken).ConfigureAwait(false); while (await reader.ReadAsync(cancellationToken).ConfigureAwait(false)) { - reader.SetExtendedAttributes(topics, markDirty: false, preserveDirtyKeys: true); + reader.SetExtendedAttributes(topics, markDirty: false, preserveDirty: true); } // Relationships From 3e84eabd179e8b3c2f2cfae845581a39db6111a1 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Thu, 2 Jul 2026 18:00:48 -0700 Subject: [PATCH 020/337] Mark `Set[Boundary]()` methods as `internal` MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit These are now all used as part of the `EnsureLoaded()` method in the `SqlTopicRepository` (de60afb4), so must be marked as `internal`. This should have been done alongside that update—whoops! --- OnTopic.Data.Sql/SqlDataReaderExtensions.cs | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs index eca0226c..c813a41d 100644 --- a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs +++ b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs @@ -262,7 +262,7 @@ private static void SetIndexedAttributes(this IDataReader reader, TopicIndex top /// behavior is overwritten to accept whatever value is submitted. This can be used, for instance, to prevent an update /// from being persisted to the data store on . /// - private static void SetExtendedAttributes(this SqlDataReader reader, TopicIndex topics, bool? markDirty) { + internal static void SetExtendedAttributes(this SqlDataReader reader, TopicIndex topics, bool? markDirty) { /*-------------------------------------------------------------------------------------------------------------------------- | Identify attributes @@ -310,6 +310,10 @@ private static void SetExtendedAttributes(this SqlDataReader reader, TopicIndex | Set attribute value \-----------------------------------------------------------------------------------------------------------------------*/ if (String.IsNullOrEmpty(attributeValue)) continue; + + // Skip keys already dirty in memory to avoid clobbering unsaved values during a lazy fill + if (preserveDirty && current.Attributes.IsDirty(attributeKey)) continue; + current.Attributes.SetValue(attributeKey, attributeValue, markDirty, version, true); } while (xmlReader.Name is "attribute"); @@ -334,7 +338,7 @@ private static void SetExtendedAttributes(this SqlDataReader reader, TopicIndex /// behavior is overwritten to accept whatever value is submitted. This can be used, for instance, to prevent an update /// from being persisted to the data store on . /// - private static void SetRelationships(this IDataReader reader, TopicIndex topics, bool? markDirty = false) { + internal static void SetRelationships(this IDataReader reader, TopicIndex topics, bool? markDirty = false) { /*-------------------------------------------------------------------------------------------------------------------------- | Identify attributes @@ -391,7 +395,7 @@ private static void SetRelationships(this IDataReader reader, TopicIndex topics, /// behavior is overwritten to accept whatever value is submitted. This can be used, for instance, to prevent an update /// from being persisted to the data store on . /// - private static void SetReferences(this IDataReader reader, TopicIndex topics, bool? markDirty) { + internal static void SetReferences(this IDataReader reader, TopicIndex topics, bool? markDirty) { /*-------------------------------------------------------------------------------------------------------------------------- | Identify attributes From afa25121638d85c29e99fc6db894f1f87ce59f94 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Thu, 2 Jul 2026 18:03:18 -0700 Subject: [PATCH 021/337] Skip reloading dirty extended attributes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit When loading extended attributes via the `EnsureLoaded()` method in the `SqlTopicRepository` (de60afb4), we don't want to overwrite dirty attributes with now-stale attributes from the SQL database. This should have been done before or alongside the update to `EnsureLoaded()` (de60afb4), since it already calls this parameter—whoops! --- OnTopic.Data.Sql/SqlDataReaderExtensions.cs | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs index c813a41d..088fee4d 100644 --- a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs +++ b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs @@ -262,7 +262,17 @@ private static void SetIndexedAttributes(this IDataReader reader, TopicIndex top /// behavior is overwritten to accept whatever value is submitted. This can be used, for instance, to prevent an update /// from being persisted to the data store on . /// - internal static void SetExtendedAttributes(this SqlDataReader reader, TopicIndex topics, bool? markDirty) { + /// + /// When true, skips any attribute key whose in-memory record is already dirty. This is used by the lazy-load + /// resolver so that a value set by the call while the extended boundary was is not + /// silently overwritten by the blob merge. + /// + internal static void SetExtendedAttributes( + this SqlDataReader reader, + TopicIndex topics, + bool? markDirty, + bool preserveDirty = false + ) { /*-------------------------------------------------------------------------------------------------------------------------- | Identify attributes From d9ce6e57c5cfa8cf79e8162fb1c868a0b841fca5 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Thu, 2 Jul 2026 18:32:20 -0700 Subject: [PATCH 022/337] Ensure extended attributes loaded before save The extended attributes are written as an XML blob, so the `SaveTopic` sproc needs all of the extended to avoid deleting any. Given that, if there are any dirty extended attributes, yet the collection isn't fully loaded, then it should be loaded from the persistence layer before saving. In practice, this isn't a likely scenario, and most scenarios where an attribute is modified in memory mean that the extended attributes were already loaded, as would happen in e.g., the editor. That said, this could still happen with e.g., programmatic updates, as we occasionally due for migrations or bulk updates. --- OnTopic.Data.Sql/SqlTopicRepository.cs | 33 ++++++++++++++++++++++---- 1 file changed, 28 insertions(+), 5 deletions(-) diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index b4b1c8a1..45a1f593 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -6,6 +6,7 @@ using System.Diagnostics.CodeAnalysis; using System.Globalization; using System.Text; +using OnTopic.Attributes; using OnTopic.Collections.Specialized; using OnTopic.Data.Sql.Models; using OnTopic.Querying; @@ -555,10 +556,11 @@ bool persistRelationships | Define variables \-------------------------------------------------------------------------------------------------------------------------*/ var isTopicDirty = topic.IsDirty(); - var areRelationshipsDirty = topic.Relationships.IsDirty(); + var areRelationshipsDirty = topic.Relationships.IsDirty(); var areReferencesDirty = topic.References.IsDirty(); var areAttributesDirty = topic.Attributes.IsDirty(true); - var extendedAttributeList = GetAttributes(topic, isExtendedAttribute: true).ToList(); + var extendedBoundaryLoaded = topic.Attributes.LoadState is LoadState.Loaded; + var extendedAttributeList = GetAttributes(topic, isExtendedAttribute: true).ToList(); var indexedAttributeList = GetAttributes( topic : topic, isExtendedAttribute : false, @@ -566,6 +568,24 @@ bool persistRelationships excludeLastModified : !areAttributesDirty ).ToList(); + /*-------------------------------------------------------------------------------------------------------------------------- + | Ensure extended attribute blob is available before save + >------------------------------------------------------------------------------------------------------------------------- + | If the extended attribute boundary is NotLoaded and at least one extended attribute is dirty, call EnsureLoaded first so + | we write a complete snapshot rather than a partial one. When the boundary is NotLoaded and no extended attrs are dirty, + | @ExtendedAttributes is omitted (NULL), leaving the persisted blob untouched (UpdateTopic guards on IS NOT NULL). + \-------------------------------------------------------------------------------------------------------------------------*/ + if (!extendedBoundaryLoaded) { + if (extendedAttributeList.Any(a => a.IsDirty)) { + EnsureLoaded(topic, LoadBoundaries.ExtendedAttributes); + extendedBoundaryLoaded = true; + extendedAttributeList = GetAttributes(topic, isExtendedAttribute: true).ToList(); + } + else { + extendedAttributeList = []; + } + } + /*-------------------------------------------------------------------------------------------------------------------------- | Detect whether anything has changed >------------------------------------------------------------------------------------------------------------------------- @@ -614,10 +634,11 @@ bool persistRelationships /*-------------------------------------------------------------------------------------------------------------------------- | Add extended attributes \-------------------------------------------------------------------------------------------------------------------------*/ - var extendedAttributes = new StringBuilder(); + var extendedAttributes = (StringBuilder?)null; - if (areAttributesDirty) { + if (areAttributesDirty && extendedBoundaryLoaded) { + extendedAttributes = new(); extendedAttributes.Append(""); foreach (var attributeValue in extendedAttributeList) { @@ -668,7 +689,9 @@ bool persistRelationships command.AddParameter("Version", version); if (areAttributesDirty) { command.AddParameter("Attributes", attributeValues); - command.AddParameter("ExtendedAttributes", extendedAttributes); + if (extendedAttributes is not null) { + command.AddParameter("ExtendedAttributes", extendedAttributes); + } } command.AddOutputParameter(); From 9475ec3eb30886e5ca865b9974cc51aa5e58d0fa Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Thu, 2 Jul 2026 20:41:37 -0700 Subject: [PATCH 023/337] Determine if extended attributes exist When returning the key attributes, add a new `HasExtendedAttributes` column which determines whether or not the topic has any extended attributes; this will be used to conditionally set `LoadState` so that `EnsureLoaded()` doesn't execute a check if we know there aren't any values. This is only needed if `@IncludeExtended` is set to `0`; otherwise, we will know whether there are extended attributes because they'll have been returned. This contributes to #111. --- .../Stored Procedures/GetTopics.sql | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/OnTopic.Data.Sql.Database/Stored Procedures/GetTopics.sql b/OnTopic.Data.Sql.Database/Stored Procedures/GetTopics.sql index 1836e536..84fa1d48 100644 --- a/OnTopic.Data.Sql.Database/Stored Procedures/GetTopics.sql +++ b/OnTopic.Data.Sql.Database/Stored Procedures/GetTopics.sql @@ -121,7 +121,23 @@ SELECT Topics.TopicID, ContentType, ParentID, TopicKey, - SortOrder + SortOrder, + HasExtendedAttributes = + CASE + WHEN @IncludeExtended = 0 + THEN CAST( + CASE + WHEN EXISTS ( + SELECT 1 + FROM ExtendedAttributeIndex AS Extended + WHERE Extended.TopicID = Topics.TopicID + ) + THEN 1 + ELSE 0 + END AS BIT + ) + ELSE NULL + END FROM Topics AS Topics JOIN #Topics AS Storage ON Storage.TopicID = Topics.TopicID From fa2dd93a2f3aa29ffb2a5607beb29b8a2cb1fac8 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Thu, 2 Jul 2026 20:57:34 -0700 Subject: [PATCH 024/337] Return topic from `AddTopic()` to avoid lookup Previously, assuming a root topic is returned, we set its ID to a `rootTopicId`, only to look it up later. Instead, just return the topic from `AddTopic()` and set that to `rootTopic`, which can be returned directly without needing to do the lookup. While I was at it, I also tidied up some indentation and a implicit conditional. --- OnTopic.Data.Sql/SqlDataReaderExtensions.cs | 33 ++++++++++++--------- 1 file changed, 19 insertions(+), 14 deletions(-) diff --git a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs index 088fee4d..a8942c57 100644 --- a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs +++ b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs @@ -52,8 +52,8 @@ internal static class SqlDataReaderExtensions { /// internal static Topic? LoadTopicGraph( this IDataReader reader, - Topic? referenceTopic = null, - bool? markDirty = null, + Topic? referenceTopic = null, + bool? markDirty = null, bool includeExternalReferences = true ) { @@ -62,17 +62,20 @@ internal static class SqlDataReaderExtensions { \-------------------------------------------------------------------------------------------------------------------------*/ var sqlDataReader = reader as SqlDataReader; var topics = referenceTopic is not null? referenceTopic.GetRootTopic().GetTopicIndex() : new(); - var rootTopicId = -1; + var rootTopic = (Topic?)null; /*-------------------------------------------------------------------------------------------------------------------------- | Populate topics \-------------------------------------------------------------------------------------------------------------------------*/ Debug.WriteLine("SqlTopicRepository.Load(): AddTopic() [" + DateTime.Now + "]"); while (reader.Read()) { - if (rootTopicId < 0) { - rootTopicId = reader.GetTopicId(); - } - reader.AddTopic(topics, markDirty); + + // Add the topic to the topic graph + var addedTopic = reader.AddTopic(topics, markDirty); + + // The first topic returned is the root topic; store it for the return value + rootTopic ??= addedTopic; + } /*-------------------------------------------------------------------------------------------------------------------------- @@ -144,10 +147,7 @@ internal static class SqlDataReaderExtensions { /*-------------------------------------------------------------------------------------------------------------------------- | Return objects \-------------------------------------------------------------------------------------------------------------------------*/ - if (topics.TryGetValue(rootTopicId, out var rootTopic)) { - return rootTopic; - } - return topics.Values.FirstOrDefault(); + return rootTopic; } @@ -166,7 +166,7 @@ internal static class SqlDataReaderExtensions { /// behavior is overwritten to accept whatever value is submitted. This can be used, for instance, to prevent an update /// from being persisted to the data store on . /// - private static void AddTopic(this IDataReader reader, TopicIndex topics, bool? markDirty) { + private static Topic AddTopic(this IDataReader reader, TopicIndex topics, bool? markDirty) { /*-------------------------------------------------------------------------------------------------------------------------- | Identify attributes @@ -200,10 +200,15 @@ private static void AddTopic(this IDataReader reader, TopicIndex topics, bool? m /*-------------------------------------------------------------------------------------------------------------------------- | Mark clean \-------------------------------------------------------------------------------------------------------------------------*/ - if (wasDirty is false && markDirty is not null and false) { + if (wasDirty is false && markDirty is false) { current.MarkClean(); } + /*-------------------------------------------------------------------------------------------------------------------------- + | Return the topic created + \-------------------------------------------------------------------------------------------------------------------------*/ + return current; + } /*============================================================================================================================ @@ -271,7 +276,7 @@ internal static void SetExtendedAttributes( this SqlDataReader reader, TopicIndex topics, bool? markDirty, - bool preserveDirty = false + bool preserveDirty = false ) { /*-------------------------------------------------------------------------------------------------------------------------- From aa19e64a04036d1516196d47306cc1bf5dac1fb5 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Thu, 2 Jul 2026 23:08:22 -0700 Subject: [PATCH 025/337] Use `HasExtendedAttributes` to set `LoadState` Use the `HasExtendedAttributes` column (9475ec3e) to determine if the extended attributes are loaded. If it is null, we know they're loaded, as the value is only set if `@IncludeExtended` is enabled. If it's 0, they weren't loaded, but there also aren't any extended attributes and, therefore, we can keep `LoadState` to its default of `Loaded` to prevent an unnecessary query in the future. Otherwise, we set `LoadState` to `NotLoaded` so that the extended attributes will be pulled on the next request. This required adding a new `GetNullableBoolean()` helper to retrieve the `HasExtendedAttributes` column correctly. This contributes to #111. --- OnTopic.Data.Sql/SqlDataReaderExtensions.cs | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs index a8942c57..c287b291 100644 --- a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs +++ b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs @@ -5,6 +5,7 @@ \=============================================================================================================================*/ using System.Diagnostics; using System.Net; +using OnTopic.Attributes; using OnTopic.Collections.Specialized; using OnTopic.Querying; @@ -76,6 +77,12 @@ internal static class SqlDataReaderExtensions { // The first topic returned is the root topic; store it for the return value rootTopic ??= addedTopic; + // HasExtendedAttribute is NULL when extended attributes are included + // HasExtendedAttribute is true when the blob wasn't loaded, but exists + if (reader.GetNullableBoolean("HasExtendedAttributes") is true) { + addedTopic.Attributes.LoadState = LoadState.NotLoaded; + } + } /*-------------------------------------------------------------------------------------------------------------------------- @@ -511,6 +518,17 @@ private static string GetString(this IDataReader reader, string columnName) => private static bool GetBoolean(this IDataReader reader, string columnName) => reader.GetBoolean(reader.GetOrdinal(columnName)); + /*============================================================================================================================ + | METHOD: GET NULLABLE BOOLEAN + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Retrieves a nullable boolean value by column name. + /// + /// The object. + /// The name of the column to retrieve the value from. + private static bool? GetNullableBoolean(this IDataReader reader, string columnName) => + reader.IsDBNull(reader.GetOrdinal(columnName))? null : reader.GetBoolean(reader.GetOrdinal(columnName)); + /*============================================================================================================================ | METHOD: GET INTEGER \---------------------------------------------------------------------------------------------------------------------------*/ From 5adf48c6461f4ca78e242e741205d5556f491707 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Thu, 2 Jul 2026 23:09:32 -0700 Subject: [PATCH 026/337] Fixed `HasExtendedAttributes` query The `AttributesXml` column is not nullable, so this should query by an empty XML value, not null. This was introduced in 9475ec3e, and fixes a bug related to #111. --- OnTopic.Data.Sql.Database/Stored Procedures/GetTopics.sql | 1 + 1 file changed, 1 insertion(+) diff --git a/OnTopic.Data.Sql.Database/Stored Procedures/GetTopics.sql b/OnTopic.Data.Sql.Database/Stored Procedures/GetTopics.sql index 84fa1d48..30a6e2f6 100644 --- a/OnTopic.Data.Sql.Database/Stored Procedures/GetTopics.sql +++ b/OnTopic.Data.Sql.Database/Stored Procedures/GetTopics.sql @@ -131,6 +131,7 @@ SELECT Topics.TopicID, SELECT 1 FROM ExtendedAttributeIndex AS Extended WHERE Extended.TopicID = Topics.TopicID + AND Extended.AttributesXml <> '' ) THEN 1 ELSE 0 From 5e4f923eb2daacb99f1be0dfc64bc1174537c7d5 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Thu, 2 Jul 2026 23:14:19 -0700 Subject: [PATCH 027/337] Added `HasExtendedAttributes` to test schema Added the newly introduced `HasExtendedAttributes` (9475ec3e, 5adf48c6) to the `TopicsDataTable` used by `OnTopic.Tests` so that it can include that in its tests. This contributes to #111. --- OnTopic.Tests/Schemas/TopicsDataTable.cs | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/OnTopic.Tests/Schemas/TopicsDataTable.cs b/OnTopic.Tests/Schemas/TopicsDataTable.cs index 85c0f443..9fbc4ad3 100644 --- a/OnTopic.Tests/Schemas/TopicsDataTable.cs +++ b/OnTopic.Tests/Schemas/TopicsDataTable.cs @@ -63,6 +63,15 @@ public TopicsDataTable() : base("Topics") { AllowDBNull = true }); + /*-------------------------------------------------------------------------------------------------------------------------- + | Add HasExtendedAttributes column + \-------------------------------------------------------------------------------------------------------------------------*/ + Columns.Add(new DataColumn() { + DataType = typeof(bool), + ColumnName = "HasExtendedAttributes", + AllowDBNull = true + }); + } /*============================================================================================================================ @@ -71,7 +80,13 @@ public TopicsDataTable() : base("Topics") { /// /// Adds a new to the . /// - public void AddRow(int topicId, string topicKey, string contentType, int? parentId = null) { + public void AddRow( + int topicId, + string topicKey, + string contentType, + int? parentId = null, + bool? hasExtendedAttributes = null + ) { /*-------------------------------------------------------------------------------------------------------------------------- | Verify parameters @@ -88,7 +103,8 @@ public void AddRow(int topicId, string topicKey, string contentType, int? parent row["TopicId"] = topicId; row["TopicKey"] = topicKey; row["ContentType"] = contentType; - row["ParentId"] = parentId.HasValue? (object)parentId : DBNull.Value; + row["ParentId"] = parentId.HasValue? parentId : DBNull.Value; + row["HasExtendedAttributes"] = hasExtendedAttributes.HasValue? hasExtendedAttributes.Value : DBNull.Value; /*-------------------------------------------------------------------------------------------------------------------------- | Add row to table From 421c7e0874ace3ea1fd5e71c39446dcf1adf0235 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Thu, 2 Jul 2026 23:19:20 -0700 Subject: [PATCH 028/337] Update SqlTopicRepositoryTest.cs Taking advantage of the newly updated `TopicsDataTable` (5e4f923e), implemented test cases of the integration between `HasExtendedAttributes` (9475ec3e, 5adf48c6) and the `LoadTopicGraph()` extension (aa19e64a). This contributes to #111. --- OnTopic.Tests/SqlTopicRepositoryTest.cs | 72 +++++++++++++++++++++++++ 1 file changed, 72 insertions(+) diff --git a/OnTopic.Tests/SqlTopicRepositoryTest.cs b/OnTopic.Tests/SqlTopicRepositoryTest.cs index b740842b..d9fbf683 100644 --- a/OnTopic.Tests/SqlTopicRepositoryTest.cs +++ b/OnTopic.Tests/SqlTopicRepositoryTest.cs @@ -365,6 +365,78 @@ public void LoadTopicGraph_WithVersionHistory_ReturnsVersions() { } + /*============================================================================================================================ + | TEST: LOAD TOPIC GRAPH: WITH EXTENDED DEFERRED AND BLOB: RETURNS NOT LOADED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Calls with a row where HasExtendedAttributes is (blob deferred), and confirms the + /// extended-attribute boundary is . + /// + [Fact] + public void LoadTopicGraph_WithExtendedDeferredAndBlob_ReturnsNotLoaded() { + + using var topics = new TopicsDataTable(); + + topics.AddRow(1, "Root", "Container", null, hasExtendedAttributes: true); + + using var tableReader = new DataTableReader(topics); + + var topic = tableReader.LoadTopicGraph(); + + Assert.NotNull(topic); + Assert.Equal(LoadState.NotLoaded, topic.Attributes.LoadState); + + } + + /*============================================================================================================================ + | TEST: LOAD TOPIC GRAPH: WITH EXTENDED DEFERRED AND NO BLOB: RETURNS LOADED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Calls with a row where HasExtendedAttributes is (blob deferred, but empty), and + /// confirms the extended-attribute boundary is , thus avoiding a wasted round-trip. + /// + [Fact] + public void LoadTopicGraph_WithExtendedDeferredAndNoBlob_ReturnsLoaded() { + + using var topics = new TopicsDataTable(); + + topics.AddRow(1, "Root", "Container", null, hasExtendedAttributes: false); + + using var tableReader = new DataTableReader(topics); + + var topic = tableReader.LoadTopicGraph(); + + Assert.NotNull(topic); + Assert.Equal(LoadState.Loaded, topic.Attributes.LoadState); + + } + + /*============================================================================================================================ + | TEST: LOAD TOPIC GRAPH: WITH EXTENDED INCLUDED AND BLOB: RETURNS LOADED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Calls with a row where HasExtendedAttributes is (extended included in result set), + /// and confirms the extended-attribute boundary is . + /// + [Fact] + public void LoadTopicGraph_WithExtendedIncludedAndBlob_ReturnsLoaded() { + + using var topics = new TopicsDataTable(); + + topics.AddRow(1, "Root", "Container", null); + + using var tableReader = new DataTableReader(topics); + + var topic = tableReader.LoadTopicGraph(); + + Assert.NotNull(topic); + Assert.Equal(LoadState.Loaded, topic.Attributes.LoadState); + + } + /*============================================================================================================================ | TEST: TOPIC LIST DATA TABLE: ADD ROW: SUCCEEDS \---------------------------------------------------------------------------------------------------------------------------*/ From 07a01cf8652d84f73e50d3948bf51be70aaeee26 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 3 Jul 2026 14:56:15 -0700 Subject: [PATCH 029/337] Renamed `LoadBoundaries` to `TopicPayload` Originally, I had intended to have two enums: `LoadBoundaries` (a0071d65) for ensuring that lazy-loaded content was loaded via `EnsureLoaded()` (59fa20d8, e25f8431), and `TopicPayload` for determining which content is loaded from `ITopicRepository.Load()`. The way `EnsureLoaded()` and `Load()` operate is different, even if they (now) share the same `GetTopics` stored procedure, in that `EnsureLoaded()` doesn't just load e.g., the Relationship and Reference IDs, but also loads each of the associated topics, if they're not already in the Topic graph. That said, two realizations have made the distinction between these a bit arbitrary. First, while, yes, the result of them may be different, they're still communicating the same concepts. Second, they should mirror each other; it doesn't make sense to make it optional to load content on Topic without having a way to `EnsureLoaded()` later. Third, the one legitimate difference, which has to do with Children, overlaps with a third `LoadScope` enum that we're planning on introducing anyway. This may change some more in the future, but as a first step, I'm merging the two concepts. Since `TopicPayload` hasn't been introduced yet but is the more intuitive name (to me), I'm renaming `LoadBoundaries` to `TopicPayload` and will implement that in the `Load()` overloads in a subsequent commit. This contributes to #111. --- OnTopic.Data.Caching/CachedTopicRepository.cs | 20 +++---- OnTopic.Data.Sql/SqlTopicRepository.cs | 45 +++++++------- .../TestDoubles/TrackingTopicLoadResolver.cs | 4 +- OnTopic.Tests/TopicRepositoryBaseTest.cs | 16 ++--- OnTopic.Tests/TopicTest.cs | 8 +-- OnTopic/Attributes/AttributeCollection.cs | 2 +- OnTopic/Repositories/ITopicLoadResolver.cs | 6 +- .../Repositories/ObservableTopicRepository.cs | 2 +- .../{LoadBoundaries.cs => TopicPayload.cs} | 25 ++++---- OnTopic/Topic.cs | 58 +++++++++---------- 10 files changed, 92 insertions(+), 94 deletions(-) rename OnTopic/Repositories/{LoadBoundaries.cs => TopicPayload.cs} (70%) diff --git a/OnTopic.Data.Caching/CachedTopicRepository.cs b/OnTopic.Data.Caching/CachedTopicRepository.cs index fef7a0ba..0dc15a88 100644 --- a/OnTopic.Data.Caching/CachedTopicRepository.cs +++ b/OnTopic.Data.Caching/CachedTopicRepository.cs @@ -131,7 +131,7 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos \---------------------------------------------------------------------------------------------------------------------------*/ /// - public virtual void EnsureLoaded(Topic topic, LoadBoundaries boundaries) { + public virtual void EnsureLoaded(Topic topic, TopicPayload boundaries) { /*-------------------------------------------------------------------------------------------------------------------------- | Validate parameters @@ -143,13 +143,13 @@ public virtual void EnsureLoaded(Topic topic, LoadBoundaries boundaries) { \-------------------------------------------------------------------------------------------------------------------------*/ // Children - if (topic.IsLoaded(LoadBoundaries.Children)) { - boundaries &= ~LoadBoundaries.Children; + if (topic.IsLoaded(TopicPayload.Children)) { + boundaries &= ~TopicPayload.Children; } // Extended Attributes - if (topic.IsLoaded(LoadBoundaries.ExtendedAttributes)) { - boundaries &= ~LoadBoundaries.ExtendedAttributes; + if (topic.IsLoaded(TopicPayload.ExtendedAttributes)) { + boundaries &= ~TopicPayload.ExtendedAttributes; } // None @@ -160,7 +160,7 @@ public virtual void EnsureLoaded(Topic topic, LoadBoundaries boundaries) { } /// - public virtual Task EnsureLoadedAsync(Topic topic, LoadBoundaries boundaries, CancellationToken cancellationToken) { + public virtual Task EnsureLoadedAsync(Topic topic, TopicPayload boundaries, CancellationToken cancellationToken) { /*-------------------------------------------------------------------------------------------------------------------------- | Validate parameters @@ -172,13 +172,13 @@ public virtual Task EnsureLoadedAsync(Topic topic, LoadBoundaries boundaries, Ca \-------------------------------------------------------------------------------------------------------------------------*/ // Children - if (topic.IsLoaded(LoadBoundaries.Children)) { - boundaries &= ~LoadBoundaries.Children; + if (topic.IsLoaded(TopicPayload.Children)) { + boundaries &= ~TopicPayload.Children; } // Extended Attributes - if (topic.IsLoaded(LoadBoundaries.ExtendedAttributes)) { - boundaries &= ~LoadBoundaries.ExtendedAttributes; + if (topic.IsLoaded(TopicPayload.ExtendedAttributes)) { + boundaries &= ~TopicPayload.ExtendedAttributes; } // None diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index 45a1f593..a0c87046 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -363,7 +363,7 @@ public override void Refresh(Topic referenceTopic, DateTime since) { \---------------------------------------------------------------------------------------------------------------------------*/ /// - public virtual void EnsureLoaded(Topic topic, LoadBoundaries boundaries) { + public virtual void EnsureLoaded(Topic topic, TopicPayload boundaries) { /*-------------------------------------------------------------------------------------------------------------------------- | Validate parameters @@ -389,7 +389,7 @@ public virtual void EnsureLoaded(Topic topic, LoadBoundaries boundaries) { /*-------------------------------------------------------------------------------------------------------------------------- | Children not yet implemented; guard before opening a connection \-------------------------------------------------------------------------------------------------------------------------*/ - if (boundaries.HasFlag(LoadBoundaries.Children)) { + if (boundaries.HasFlag(TopicPayload.Children)) { throw new NotImplementedException("Per-level child loading will be implemented in Task 5."); } @@ -401,7 +401,7 @@ public virtual void EnsureLoaded(Topic topic, LoadBoundaries boundaries) { CommandType = CommandType.StoredProcedure }; - // Set the stored procedure parameters based on the LoadBoundaries enum values + // Set the stored procedure parameters based on the TopicPayload enum values AddEnsureLoadedParameters(command, topic.Id, boundaries); /*-------------------------------------------------------------------------------------------------------------------------- @@ -453,7 +453,7 @@ public virtual void EnsureLoaded(Topic topic, LoadBoundaries boundaries) { } /// - public virtual async Task EnsureLoadedAsync(Topic topic, LoadBoundaries boundaries, CancellationToken cancellationToken) { + public virtual async Task EnsureLoadedAsync(Topic topic, TopicPayload boundaries, CancellationToken cancellationToken) { /*-------------------------------------------------------------------------------------------------------------------------- | Validate parameters @@ -479,7 +479,7 @@ public virtual async Task EnsureLoadedAsync(Topic topic, LoadBoundaries boundari /*-------------------------------------------------------------------------------------------------------------------------- | Children not yet implemented; guard before opening a connection \-------------------------------------------------------------------------------------------------------------------------*/ - if (boundaries.HasFlag(LoadBoundaries.Children)) { + if (boundaries.HasFlag(TopicPayload.Children)) { throw new NotImplementedException("Per-level child loading will be implemented in Task 5."); } @@ -491,7 +491,7 @@ public virtual async Task EnsureLoadedAsync(Topic topic, LoadBoundaries boundari CommandType = CommandType.StoredProcedure }; - // Set the stored procedure parameters based on the LoadBoundaries enum values + // Set the stored procedure parameters based on the TopicPayload enum values AddEnsureLoadedParameters(command, topic.Id, boundaries); /*-------------------------------------------------------------------------------------------------------------------------- @@ -577,7 +577,7 @@ bool persistRelationships \-------------------------------------------------------------------------------------------------------------------------*/ if (!extendedBoundaryLoaded) { if (extendedAttributeList.Any(a => a.IsDirty)) { - EnsureLoaded(topic, LoadBoundaries.ExtendedAttributes); + EnsureLoaded(topic, TopicPayload.ExtendedAttributes); extendedBoundaryLoaded = true; extendedAttributeList = GetAttributes(topic, isExtendedAttribute: true).ToList(); } @@ -841,20 +841,20 @@ protected override sealed void DeleteTopic(Topic topic) { /// Marks each boundary in as on the given /// after a successful resolver fill. /// - private static void MarkBoundariesLoaded(Topic topic, LoadBoundaries boundaries) { + private static void MarkBoundariesLoaded(Topic topic, TopicPayload boundaries) { // Extended attributes - if (boundaries.HasFlag(LoadBoundaries.ExtendedAttributes)) { + if (boundaries.HasFlag(TopicPayload.ExtendedAttributes)) { topic.Attributes.LoadState = LoadState.Loaded; } // Relationships - if (boundaries.HasFlag(LoadBoundaries.Relationships)) { + if (boundaries.HasFlag(TopicPayload.Relationships)) { topic.Relationships.LoadState = LoadState.Loaded; } // References - if (boundaries.HasFlag(LoadBoundaries.References)) { + if (boundaries.HasFlag(TopicPayload.References)) { topic.References.LoadState = LoadState.Loaded; } @@ -868,11 +868,12 @@ private static void MarkBoundariesLoaded(Topic topic, LoadBoundaries boundaries) /// setting the payload parameters based on the requested . /// /// - /// Scope is always None (i.e., a single node) for resolver fills, as the caller is already in the graph. History - /// is never a lazy-load boundary and so is always excluded. Indexed attributes are only requested when filling the boundary. + /// Scope is always None (i.e., a single node) for resolver fills, as the caller is already in the graph. is hardcoded to false here because its fill path is not yet implemented; once + /// it is, this method will map it from the flag. Indexed attributes are only requested when + /// filling the boundary. /// - private static void AddEnsureLoadedParameters(SqlCommand command, int topicId, LoadBoundaries boundaries) { + private static void AddEnsureLoadedParameters(SqlCommand command, int topicId, TopicPayload boundaries) { // Set the topic we're working with command.AddParameter("TopicID", topicId); @@ -882,10 +883,10 @@ private static void AddEnsureLoadedParameters(SqlCommand command, int topicId, L command.AddParameter("LoadAscendants", false); // Payload: Include only what the requested boundaries require - command.AddParameter("IncludeIndexed", boundaries.HasFlag(LoadBoundaries.Children)); - command.AddParameter("IncludeExtended", boundaries.HasFlag(LoadBoundaries.ExtendedAttributes)); - command.AddParameter("IncludeRelationships", boundaries.HasFlag(LoadBoundaries.Relationships)); - command.AddParameter("IncludeReferences", boundaries.HasFlag(LoadBoundaries.References)); + command.AddParameter("IncludeIndexed", boundaries.HasFlag(TopicPayload.Children)); + command.AddParameter("IncludeExtended", boundaries.HasFlag(TopicPayload.ExtendedAttributes)); + command.AddParameter("IncludeRelationships", boundaries.HasFlag(TopicPayload.Relationships)); + command.AddParameter("IncludeReferences", boundaries.HasFlag(TopicPayload.References)); command.AddParameter("IncludeHistory", false); } @@ -897,13 +898,13 @@ private static void AddEnsureLoadedParameters(SqlCommand command, int topicId, L /// Returns with any already- flags cleared, so that and skip redundant round-trips. /// - private static LoadBoundaries FilterLoadedBoundaries(Topic topic, LoadBoundaries boundaries) { + private static TopicPayload FilterLoadedBoundaries(Topic topic, TopicPayload boundaries) { // Loop through all boundaries - foreach (LoadBoundaries flag in Enum.GetValues()) { + foreach (TopicPayload flag in Enum.GetValues()) { // Skip None (0) and All (composite) - if (flag is LoadBoundaries.None or LoadBoundaries.All) { + if (flag is TopicPayload.None or TopicPayload.All) { continue; } diff --git a/OnTopic.Tests/TestDoubles/TrackingTopicLoadResolver.cs b/OnTopic.Tests/TestDoubles/TrackingTopicLoadResolver.cs index e23ef087..5fbba101 100644 --- a/OnTopic.Tests/TestDoubles/TrackingTopicLoadResolver.cs +++ b/OnTopic.Tests/TestDoubles/TrackingTopicLoadResolver.cs @@ -29,7 +29,7 @@ internal sealed class TrackingTopicLoadResolver : ITopicLoadResolver { | METHOD: ENSURE LOADED \---------------------------------------------------------------------------------------------------------------------------*/ /// - void ITopicLoadResolver.EnsureLoaded(Topic topic, LoadBoundaries boundaries) => WasCalled = true; + void ITopicLoadResolver.EnsureLoaded(Topic topic, TopicPayload boundaries) => WasCalled = true; /*============================================================================================================================ | METHOD: ENSURE LOADED (ASYNC) @@ -37,7 +37,7 @@ internal sealed class TrackingTopicLoadResolver : ITopicLoadResolver { /// Task ITopicLoadResolver.EnsureLoadedAsync( Topic topic, - LoadBoundaries boundaries, + TopicPayload boundaries, CancellationToken cancellationToken ) { WasCalled = true; diff --git a/OnTopic.Tests/TopicRepositoryBaseTest.cs b/OnTopic.Tests/TopicRepositoryBaseTest.cs index 21315c7d..4c2cc065 100644 --- a/OnTopic.Tests/TopicRepositoryBaseTest.cs +++ b/OnTopic.Tests/TopicRepositoryBaseTest.cs @@ -1124,7 +1124,7 @@ public void Save_NewTopic_StampsResolver() { \---------------------------------------------------------------------------------------------------------------------------*/ /// /// Loads a whose extended-attribute boundary has been manually set to - /// and confirms that promotes the boundary to promotes the boundary to via the 's fill. /// [Fact] @@ -1133,9 +1133,9 @@ public void EnsureLoaded_ExtendedAttributesNotLoaded_MarksLoaded() { var topic = _topicRepository.Load(11111); topic!.Attributes.LoadState = LoadState.NotLoaded; - topic.EnsureLoaded(LoadBoundaries.ExtendedAttributes); + topic.EnsureLoaded(TopicPayload.ExtendedAttributes); - Assert.True(topic.IsLoaded(LoadBoundaries.ExtendedAttributes)); + Assert.True(topic.IsLoaded(TopicPayload.ExtendedAttributes)); } @@ -1143,7 +1143,7 @@ public void EnsureLoaded_ExtendedAttributesNotLoaded_MarksLoaded() { | TEST: ENSURE LOADED: MIXED BOUNDARIES: SKIPS LOADED BOUNDARIES \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Calls with a mixed set of flags, including one already set to with a mixed set of flags, including one already set to and one , and confirms that only the pending boundary is /// forwarded to the resolver, leaving the already-loaded boundary unchanged. /// @@ -1153,11 +1153,11 @@ public void EnsureLoaded_MixedBoundaries_SkipsLoadedBoundaries() { var topic = _topicRepository.Load(11111); topic!.Attributes.LoadState = LoadState.NotLoaded; - Assert.True(topic.IsLoaded(LoadBoundaries.Children)); - topic.EnsureLoaded(LoadBoundaries.Children | LoadBoundaries.ExtendedAttributes); + Assert.True(topic.IsLoaded(TopicPayload.Children)); + topic.EnsureLoaded(TopicPayload.Children | TopicPayload.ExtendedAttributes); - Assert.True(topic.IsLoaded(LoadBoundaries.ExtendedAttributes)); - Assert.True(topic.IsLoaded(LoadBoundaries.Children)); + Assert.True(topic.IsLoaded(TopicPayload.ExtendedAttributes)); + Assert.True(topic.IsLoaded(TopicPayload.Children)); } diff --git a/OnTopic.Tests/TopicTest.cs b/OnTopic.Tests/TopicTest.cs index 1bc17193..37bd2636 100644 --- a/OnTopic.Tests/TopicTest.cs +++ b/OnTopic.Tests/TopicTest.cs @@ -533,20 +533,20 @@ public void MarkClean_NewTopic_RemainsDirty() { | TEST: ENSURE LOADED: NULL RESOLVER: DOES NOT THROW \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Calls on an in-memory topic with no resolver and confirms it completes + /// Calls on an in-memory topic with no resolver and confirms it completes /// without throwing. /// [Fact] public void EnsureLoaded_NullResolver_DoesNotThrow() { var topic = new Topic("Topic", "Page"); - topic.EnsureLoaded(LoadBoundaries.All); + topic.EnsureLoaded(TopicPayload.All); } /*============================================================================================================================ | TEST: ENSURE LOADED: IS NEW: DOES NOT INVOKE RESOLVER \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Calls on a new topic (no ) that has a resolver + /// Calls on a new topic (no ) that has a resolver /// stamped on it and confirms the resolver is not invoked. /// /// @@ -571,7 +571,7 @@ public void EnsureLoaded_IsNew_DoesNotInvokeResolver() { /*-------------------------------------------------------------------------------------------------------------------------- | Verify resolver is not called \-------------------------------------------------------------------------------------------------------------------------*/ - topic.EnsureLoaded(LoadBoundaries.Children); + topic.EnsureLoaded(TopicPayload.Children); Assert.False(tracker.WasCalled); } diff --git a/OnTopic/Attributes/AttributeCollection.cs b/OnTopic/Attributes/AttributeCollection.cs index 121eac3b..d0a04a64 100644 --- a/OnTopic/Attributes/AttributeCollection.cs +++ b/OnTopic/Attributes/AttributeCollection.cs @@ -119,7 +119,7 @@ public bool IsDirty(bool excludeLastModified) [return: NotNullIfNotNull(nameof(defaultValue))] internal override string? GetValue(string key, string? defaultValue, bool inheritFromParent, int maxHops) { if (LoadState is LoadState.NotLoaded && !Contains(key)) { - AssociatedTopic.EnsureLoaded(LoadBoundaries.ExtendedAttributes); + AssociatedTopic.EnsureLoaded(TopicPayload.ExtendedAttributes); } return base.GetValue(key, defaultValue, inheritFromParent, maxHops); } diff --git a/OnTopic/Repositories/ITopicLoadResolver.cs b/OnTopic/Repositories/ITopicLoadResolver.cs index 61fc2e3b..67cfe21a 100644 --- a/OnTopic/Repositories/ITopicLoadResolver.cs +++ b/OnTopic/Repositories/ITopicLoadResolver.cs @@ -24,9 +24,9 @@ public interface ITopicLoadResolver { /// fetching and merging whichever of them are not yet and silently skipping those already /// loaded. Invoked by the autoloading property getters, each with its own flag. /// - void EnsureLoaded(Topic topic, LoadBoundaries boundaries); + void EnsureLoaded(Topic topic, TopicPayload boundaries); - /// - Task EnsureLoadedAsync(Topic topic, LoadBoundaries boundaries, CancellationToken cancellationToken = default); + /// + Task EnsureLoadedAsync(Topic topic, TopicPayload boundaries, CancellationToken cancellationToken = default); } //Interface \ No newline at end of file diff --git a/OnTopic/Repositories/ObservableTopicRepository.cs b/OnTopic/Repositories/ObservableTopicRepository.cs index c338438d..c5d803fc 100644 --- a/OnTopic/Repositories/ObservableTopicRepository.cs +++ b/OnTopic/Repositories/ObservableTopicRepository.cs @@ -294,7 +294,7 @@ protected void StampResolver(Topic? topic) { topic._resolver = resolver; // If the children aren't yet loaded, don't bother with them yet - if (!topic.IsLoaded(LoadBoundaries.Children)) { + if (!topic.IsLoaded(TopicPayload.Children)) { return; } diff --git a/OnTopic/Repositories/LoadBoundaries.cs b/OnTopic/Repositories/TopicPayload.cs similarity index 70% rename from OnTopic/Repositories/LoadBoundaries.cs rename to OnTopic/Repositories/TopicPayload.cs index ffae3878..9ac5133f 100644 --- a/OnTopic/Repositories/LoadBoundaries.cs +++ b/OnTopic/Repositories/TopicPayload.cs @@ -7,21 +7,22 @@ namespace OnTopic.Repositories; /*============================================================================================================================== -| ENUM: LOAD BOUNDARIES +| ENUM: TOPIC PAYLOAD \-----------------------------------------------------------------------------------------------------------------------------*/ /// -/// Identifies one or more deferred boundaries on a that have not yet been retrieved from the underlying -/// . Used by to specify which boundaries to ensure are loaded. +/// Specifies which data ensure is loaded on a . Used as a parameter on 's +/// Load() overloads to control how much data is fetched in the first place, and on 's +/// Ensure() method to specify which previously deferred data to fill on demand. /// [Flags] -public enum LoadBoundaries { +public enum TopicPayload { /*---------------------------------------------------------------------------------------------------------------------------- | NONE \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// No boundaries are requested. Passing this value to will result in nothing - /// being loaded. + /// No additional payload is requested. Indexed attributes are always returned as part of the base graph; this value + /// represents the lean baseline, with all available by specifying the additional values. /// None = 0, @@ -38,8 +39,7 @@ public enum LoadBoundaries { | EXTENDED ATTRIBUTES \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// The topic's extended attributes have not been fetched. Accessing a deferred attribute on - /// will trigger an on-demand load of the entire extended attributes blob for the topic. + /// Extended attributes are loaded alongside the indexed attributes. /// ExtendedAttributes = 2, @@ -47,8 +47,7 @@ public enum LoadBoundaries { | RELATIONSHIPS \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// The topic's relationship targets have not been fully resolved. Accessing will trigger - /// an on-demand load of all relationships associated with the topic. + /// Relationship targets are included. /// Relationships = 4, @@ -56,8 +55,7 @@ public enum LoadBoundaries { | REFERENCES \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// The topic's reference targets have not been fully resolved. Accessing will trigger an - /// on-demand load of all references associated with the topic. + /// Topic reference targets are included. /// References = 8, @@ -65,8 +63,7 @@ public enum LoadBoundaries { | ALL \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// All four deferred boundaries. Passing this flag to ensures that every - /// deferred boundary on the topic is populated. + /// All payload data. This ensures a comprehensive loading of all available data. /// All = Children | ExtendedAttributes | Relationships | References, diff --git a/OnTopic/Topic.cs b/OnTopic/Topic.cs index 117b3da2..ca3cfeb9 100644 --- a/OnTopic/Topic.cs +++ b/OnTopic/Topic.cs @@ -174,26 +174,26 @@ public Topic? Parent { /// Reads each collection's directly without touching any autoloading getter, making it safe to /// use in traversal and "gating" logic that should not trigger lazy-loading. /// - /// One or more flags to test. - public bool IsLoaded(LoadBoundaries boundaries) { + /// One or more flags to test. + public bool IsLoaded(TopicPayload boundaries) { // Children - if (boundaries.HasFlag(LoadBoundaries.Children) && Children.LoadState is not LoadState.Loaded) { + if (boundaries.HasFlag(TopicPayload.Children) && Children.LoadState is not LoadState.Loaded) { return false; } // Extended Attributes - if (boundaries.HasFlag(LoadBoundaries.ExtendedAttributes) && Attributes.LoadState is not LoadState.Loaded) { + if (boundaries.HasFlag(TopicPayload.ExtendedAttributes) && Attributes.LoadState is not LoadState.Loaded) { return false; } // Relationships - if (boundaries.HasFlag(LoadBoundaries.Relationships) && Relationships.LoadState is not LoadState.Loaded) { + if (boundaries.HasFlag(TopicPayload.Relationships) && Relationships.LoadState is not LoadState.Loaded) { return false; } // References - if (boundaries.HasFlag(LoadBoundaries.References) && References.LoadState is not LoadState.Loaded) { + if (boundaries.HasFlag(TopicPayload.References) && References.LoadState is not LoadState.Loaded) { return false; } @@ -217,9 +217,9 @@ public bool IsLoaded(LoadBoundaries boundaries) { /// node's mapping needs in a single round trip. /// /// - /// One or more flags identifying the boundaries that should be ensured to be loaded. + /// One or more flags identifying the boundaries that should be ensured to be loaded. /// - public void EnsureLoaded(LoadBoundaries boundaries) { + public void EnsureLoaded(TopicPayload boundaries) { /*-------------------------------------------------------------------------------------------------------------------------- | Skip for obvious reasons @@ -233,27 +233,27 @@ public void EnsureLoaded(LoadBoundaries boundaries) { \-------------------------------------------------------------------------------------------------------------------------*/ // Children - if (IsLoaded(LoadBoundaries.Children)) { - boundaries &= ~LoadBoundaries.Children; + if (IsLoaded(TopicPayload.Children)) { + boundaries &= ~TopicPayload.Children; } // ExtendedAttributes - if (IsLoaded(LoadBoundaries.ExtendedAttributes)) { - boundaries &= ~LoadBoundaries.ExtendedAttributes; + if (IsLoaded(TopicPayload.ExtendedAttributes)) { + boundaries &= ~TopicPayload.ExtendedAttributes; } // Relationships - if (IsLoaded(LoadBoundaries.Relationships)) { - boundaries &= ~LoadBoundaries.Relationships; + if (IsLoaded(TopicPayload.Relationships)) { + boundaries &= ~TopicPayload.Relationships; } // References - if (IsLoaded(LoadBoundaries.References)) { - boundaries &= ~LoadBoundaries.References; + if (IsLoaded(TopicPayload.References)) { + boundaries &= ~TopicPayload.References; } // None - if (boundaries is LoadBoundaries.None) { + if (boundaries is TopicPayload.None) { return; } @@ -262,12 +262,12 @@ public void EnsureLoaded(LoadBoundaries boundaries) { } - /// + /// /// - /// One or more flags identifying the boundaries that should be ensured to be loaded. + /// One or more flags identifying the boundaries that should be ensured to be loaded. /// /// An optional token that can be used to cancel the operation. - public Task EnsureLoadedAsync(LoadBoundaries boundaries, CancellationToken cancellationToken = default) { + public Task EnsureLoadedAsync(TopicPayload boundaries, CancellationToken cancellationToken = default) { /*-------------------------------------------------------------------------------------------------------------------------- | Skip for obvious reasons @@ -281,27 +281,27 @@ public Task EnsureLoadedAsync(LoadBoundaries boundaries, CancellationToken cance \-------------------------------------------------------------------------------------------------------------------------*/ // Children - if (IsLoaded(LoadBoundaries.Children)) { - boundaries &= ~LoadBoundaries.Children; + if (IsLoaded(TopicPayload.Children)) { + boundaries &= ~TopicPayload.Children; } // Extended Attributes - if (IsLoaded(LoadBoundaries.ExtendedAttributes)) { - boundaries &= ~LoadBoundaries.ExtendedAttributes; + if (IsLoaded(TopicPayload.ExtendedAttributes)) { + boundaries &= ~TopicPayload.ExtendedAttributes; } // Relationships - if (IsLoaded(LoadBoundaries.Relationships)) { - boundaries &= ~LoadBoundaries.Relationships; + if (IsLoaded(TopicPayload.Relationships)) { + boundaries &= ~TopicPayload.Relationships; } // References - if (IsLoaded(LoadBoundaries.References)) { - boundaries &= ~LoadBoundaries.References; + if (IsLoaded(TopicPayload.References)) { + boundaries &= ~TopicPayload.References; } // None - if (boundaries is LoadBoundaries.None) { + if (boundaries is TopicPayload.None) { return Task.CompletedTask; } From 58524089d3f8531b9246f1fb96f7b124769c991e Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 3 Jul 2026 15:28:24 -0700 Subject: [PATCH 030/337] Added `TopicPayload` to most `Load()` overloads This adds the newly renamed `TopicPayload` flags enum (07a01cf8) to the two primary `Load()` overloads on `ITopicRepository` and it's implementations. While this isn't yet wired up to anything, it lays the groundwork for lazy-loading (#111) as this will eventually allow the `Load()` methods to only load the exact data they need, while deferring the rest to be lazy-loaded as requested. Because this is on the common overload of `Load()`, many of these are just updates to XML Doc references, which required reformatting much of the block. Similarly, the length of this overload required reformatting the actual signatures to use the multi-line format. --- .../Repositories/StubTopicRepository.cs | 15 ++++++++++++-- OnTopic.Data.Caching/CachedTopicRepository.cs | 14 +++++++++++-- OnTopic.Data.Sql/SqlTopicRepository.cs | 17 +++++++++++++--- OnTopic.TestDoubles/DummyTopicRepository.cs | 14 +++++++++++-- OnTopic.TestDoubles/StubTopicRepository.cs | 20 ++++++++++++++----- OnTopic.Tests/TopicRepositoryBaseTest.cs | 14 ++++++------- .../Associations/TopicReferenceCollection.cs | 4 ++-- .../Associations/TopicRelationshipMultiMap.cs | 2 +- .../Specialized/TrackedRecord{T}.cs | 9 +++++---- OnTopic/Repositories/ITopicRepository.cs | 15 +++++++++----- .../Repositories/ObservableTopicRepository.cs | 18 +++++++++++++---- .../Repositories/TopicRepositoryDecorator.cs | 18 +++++++++++++---- .../_eventArgs/TopicLoadEventArgs.cs | 2 +- 13 files changed, 120 insertions(+), 42 deletions(-) diff --git a/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/Repositories/StubTopicRepository.cs b/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/Repositories/StubTopicRepository.cs index b4fd5ab1..7bffae43 100644 --- a/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/Repositories/StubTopicRepository.cs +++ b/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/Repositories/StubTopicRepository.cs @@ -42,7 +42,13 @@ public StubTopicRepository() : base() { | METHOD: LOAD \---------------------------------------------------------------------------------------------------------------------------*/ /// - public override Topic? Load(int topicId, Topic? referenceTopic = null, bool isRecursive = true) { + public override Topic? Load( + int topicId, + Topic? referenceTopic = null, + bool isRecursive = true, + TopicPayload payload = TopicPayload.All + ) { + /*-------------------------------------------------------------------------------------------------------------------------- | Lookup by TopicId @@ -68,7 +74,12 @@ public StubTopicRepository() : base() { } /// - public override Topic? Load(string uniqueKey, Topic? referenceTopic = null, bool isRecursive = true) { + public override Topic? Load( + string uniqueKey, + Topic? referenceTopic = null, + bool isRecursive = true, + TopicPayload payload = TopicPayload.All + ) { /*-------------------------------------------------------------------------------------------------------------------------- | Validate parameters diff --git a/OnTopic.Data.Caching/CachedTopicRepository.cs b/OnTopic.Data.Caching/CachedTopicRepository.cs index 0dc15a88..54d7a8ba 100644 --- a/OnTopic.Data.Caching/CachedTopicRepository.cs +++ b/OnTopic.Data.Caching/CachedTopicRepository.cs @@ -67,7 +67,12 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos | METHOD: LOAD \---------------------------------------------------------------------------------------------------------------------------*/ /// - public override Topic? Load(int topicId, Topic? referenceTopic = null, bool isRecursive = true) { + public override Topic? Load( + int topicId, + Topic? referenceTopic = null, + bool isRecursive = true, + TopicPayload payload = TopicPayload.All + ) { /*-------------------------------------------------------------------------------------------------------------------------- | Handle request for entire tree @@ -84,7 +89,12 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos } /// - public override Topic? Load(string uniqueKey, Topic? referenceTopic = null, bool isRecursive = true) { + public override Topic? Load( + string uniqueKey, + Topic? referenceTopic = null, + bool isRecursive = true, + TopicPayload payload = TopicPayload.All + ) { /*-------------------------------------------------------------------------------------------------------------------------- | Validate parameters diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index a0c87046..15cc9bbb 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -57,7 +57,12 @@ public SqlTopicRepository(string connectionString) : base() { | METHOD: LOAD \---------------------------------------------------------------------------------------------------------------------------*/ /// - public override Topic Load(string uniqueKey, Topic? referenceTopic = null, bool isRecursive = true) { + public override Topic Load( + string uniqueKey, + Topic? referenceTopic = null, + bool isRecursive = true, + TopicPayload payload = TopicPayload.All + ) { /*-------------------------------------------------------------------------------------------------------------------------- | Validate parameters @@ -110,12 +115,17 @@ public override Topic Load(string uniqueKey, Topic? referenceTopic = null, bool /*-------------------------------------------------------------------------------------------------------------------------- | Return topic \-------------------------------------------------------------------------------------------------------------------------*/ - return Load(topicId, referenceTopic, isRecursive); + return Load(topicId, referenceTopic, isRecursive, payload); } /// - public override Topic Load(int topicId, Topic? referenceTopic = null, bool isRecursive = true) { + public override Topic Load( + int topicId, + Topic? referenceTopic = null, + bool isRecursive = true, + TopicPayload payload = TopicPayload.All + ) { /*-------------------------------------------------------------------------------------------------------------------------- | Establish database connection @@ -134,6 +144,7 @@ public override Topic Load(int topicId, Topic? referenceTopic = null, bool isRec command.AddParameter("TopicID", topicId); command.AddParameter("LoadDescendants", isRecursive); command.AddParameter("LoadAscendants", !isRecursive); + command.AddParameter("IncludeExtended", payload.HasFlag(TopicPayload.ExtendedAttributes)); /*-------------------------------------------------------------------------------------------------------------------------- | Process database query diff --git a/OnTopic.TestDoubles/DummyTopicRepository.cs b/OnTopic.TestDoubles/DummyTopicRepository.cs index f683903e..9fbdafa2 100644 --- a/OnTopic.TestDoubles/DummyTopicRepository.cs +++ b/OnTopic.TestDoubles/DummyTopicRepository.cs @@ -36,10 +36,20 @@ public DummyTopicRepository() : base() { } | METHOD: LOAD \---------------------------------------------------------------------------------------------------------------------------*/ /// - public override Topic? Load(int topicId, Topic? referenceTopic = null, bool isRecursive = true) => null; + public override Topic? Load( + int topicId, + Topic? referenceTopic = null, + bool isRecursive = true, + TopicPayload payload = TopicPayload.All + ) => null; /// - public override Topic? Load(string uniqueKey, Topic? referenceTopic = null, bool isRecursive = true) => null; + public override Topic? Load( + string uniqueKey, + Topic? referenceTopic = null, + bool isRecursive = true, + TopicPayload payload = TopicPayload.All + ) => null; /// public override Topic? Load(Topic? topic, DateTime version) => throw new NotImplementedException(); diff --git a/OnTopic.TestDoubles/StubTopicRepository.cs b/OnTopic.TestDoubles/StubTopicRepository.cs index 6ef85b64..9cc2e05e 100644 --- a/OnTopic.TestDoubles/StubTopicRepository.cs +++ b/OnTopic.TestDoubles/StubTopicRepository.cs @@ -47,7 +47,12 @@ public StubTopicRepository() : base() { | METHOD: LOAD \---------------------------------------------------------------------------------------------------------------------------*/ /// - public override Topic? Load(int topicId, Topic? referenceTopic = null, bool isRecursive = true) { + public override Topic? Load( + int topicId, + Topic? referenceTopic = null, + bool isRecursive = true, + TopicPayload payload = TopicPayload.All + ) { /*-------------------------------------------------------------------------------------------------------------------------- | Lookup by TopicId @@ -80,7 +85,12 @@ public StubTopicRepository() : base() { } /// - public override Topic? Load(string uniqueKey, Topic? referenceTopic = null, bool isRecursive = true) { + public override Topic? Load( + string uniqueKey, + Topic? referenceTopic = null, + bool isRecursive = true, + TopicPayload payload = TopicPayload.All + ) { /*-------------------------------------------------------------------------------------------------------------------------- | Validate parameters @@ -198,7 +208,7 @@ protected override void SaveTopic([NotNull]Topic topic, DateTime version, bool p /// database. /// /// - public virtual void EnsureLoaded(Topic topic, LoadBoundaries boundaries) { + public virtual void EnsureLoaded(Topic topic, TopicPayload boundaries) { /*-------------------------------------------------------------------------------------------------------------------------- | Validate parameters @@ -208,14 +218,14 @@ public virtual void EnsureLoaded(Topic topic, LoadBoundaries boundaries) { /*-------------------------------------------------------------------------------------------------------------------------- | Mark extended attribute boundary as loaded; this is a no-op for children, as it's already populated in the stubs \-------------------------------------------------------------------------------------------------------------------------*/ - if (boundaries.HasFlag(LoadBoundaries.ExtendedAttributes) && topic.Attributes.LoadState is LoadState.NotLoaded) { + if (boundaries.HasFlag(TopicPayload.ExtendedAttributes) && topic.Attributes.LoadState is LoadState.NotLoaded) { topic.Attributes.LoadState = LoadState.Loaded; } } /// - public virtual Task EnsureLoadedAsync(Topic topic, LoadBoundaries boundaries, CancellationToken cancellationToken) { + public virtual Task EnsureLoadedAsync(Topic topic, TopicPayload boundaries, CancellationToken cancellationToken) { EnsureLoaded(topic, boundaries); return Task.CompletedTask; } diff --git a/OnTopic.Tests/TopicRepositoryBaseTest.cs b/OnTopic.Tests/TopicRepositoryBaseTest.cs index 4c2cc065..6196c8c9 100644 --- a/OnTopic.Tests/TopicRepositoryBaseTest.cs +++ b/OnTopic.Tests/TopicRepositoryBaseTest.cs @@ -52,8 +52,8 @@ public TopicRepositoryBaseTest() { | TEST: LOAD: VALID TOPIC ID: RETURNS EXPECTED TOPIC \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Calls with a valid and - /// confirms that the expected topic is returned. + /// Calls with a valid + /// and confirms that the expected topic is returned. /// [Fact] public void Load_ValidTopicId_ReturnsExpectedTopic() { @@ -68,8 +68,8 @@ public void Load_ValidTopicId_ReturnsExpectedTopic() { | TEST: LOAD: INVALID TOPIC ID: RETURNS EXPECTED TOPIC \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Calls with an invalid and - /// confirms that no topic is returned. + /// Calls with an invalid and confirms that no topic is returned. /// [Fact] public void Load_InvalidTopicId_ReturnsExpectedTopic() => @@ -79,8 +79,8 @@ public void Load_InvalidTopicId_ReturnsExpectedTopic() => | TEST: LOAD: NEGATIVE TOPIC ID: RETURNS ROOT TOPIC \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Calls with a negative and - /// confirms that the root topic is returned. + /// Calls with a negative and confirms that the root topic is returned. /// [Fact] public void Load_NegativeTopicId_ReturnsRootTopic() => @@ -954,7 +954,7 @@ public void Delete_AttributeDescriptor_UpdatesContentTypeCache() { | TEST: LOAD: TOPIC LOADED EVENT: IS RAISED \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Loads a topic using and ensures that the and ensures that the event is raised. /// [Fact] diff --git a/OnTopic/Associations/TopicReferenceCollection.cs b/OnTopic/Associations/TopicReferenceCollection.cs index 356f0910..aa81b5e9 100644 --- a/OnTopic/Associations/TopicReferenceCollection.cs +++ b/OnTopic/Associations/TopicReferenceCollection.cs @@ -71,8 +71,8 @@ public TopicReferenceCollection(Topic parentTopic) : base(parentTopic) { } /// /// /// The property defaults to true. It should be set to false during the method if any members of the collection cannot be mapped - /// back to a valid reference in memory. + /// cref="ITopicRepository.Load(String, Topic?, Boolean, TopicPayload)"/> method if any members of the collection cannot + /// be mapped back to a valid reference in memory. /// /// public bool IsFullyLoaded { diff --git a/OnTopic/Associations/TopicRelationshipMultiMap.cs b/OnTopic/Associations/TopicRelationshipMultiMap.cs index 0b975baf..0e1ac95d 100644 --- a/OnTopic/Associations/TopicRelationshipMultiMap.cs +++ b/OnTopic/Associations/TopicRelationshipMultiMap.cs @@ -270,7 +270,7 @@ public void SetTopic(string relationshipKey, Topic topic, bool? isDirty, bool is /// /// /// The property defaults to true. It should be set to false during the method if any members of the collection cannot be mapped + /// cref="ITopicRepository.Load(String, Topic?, Boolean, TopicPayload)"/> method if any members of the collection cannot be mapped /// back to a valid reference in memory. /// /// diff --git a/OnTopic/Collections/Specialized/TrackedRecord{T}.cs b/OnTopic/Collections/Specialized/TrackedRecord{T}.cs index 3547dff3..250a51dc 100644 --- a/OnTopic/Collections/Specialized/TrackedRecord{T}.cs +++ b/OnTopic/Collections/Specialized/TrackedRecord{T}.cs @@ -102,10 +102,11 @@ protected TrackedRecord(string key, T? value, bool isDirty = true, DateTime? las /// Gets the for the given item. /// /// - /// If loaded from a data store from e.g. , the should be set to the Version. If the is novel, however, then it should be - /// set to the current date. That won't be the same date established by for the Version, however, which is why this property is labeled . + /// If loaded from a data store from e.g. , the + /// should be set to the Version. If the is novel, however, then it + /// should be set to the current date. That won't be the same date established by for the Version, however, which is why this property is labeled . /// public DateTime LastModified { get; init; } diff --git a/OnTopic/Repositories/ITopicRepository.cs b/OnTopic/Repositories/ITopicRepository.cs index bb00114b..95d25dc0 100644 --- a/OnTopic/Repositories/ITopicRepository.cs +++ b/OnTopic/Repositories/ITopicRepository.cs @@ -20,8 +20,8 @@ public interface ITopicRepository { \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Raised after a is loaded from the as part of a operation, or one of its overloads. + /// Raised after a is loaded from the as part of a operation, or one of its overloads. /// /// /// The event should only be raised when a new is loaded from the underlying @@ -98,8 +98,9 @@ public interface ITopicRepository { /// associations—such as references, relationships, and —are integrated with existing entities. /// /// Determines whether or not to recurse through and load a topic's children. + /// Specifies which data to include with each topic. /// A topic object. - Topic? Load(int topicId, Topic? referenceTopic = null, bool isRecursive = true); + Topic? Load(int topicId, Topic? referenceTopic = null, bool isRecursive = true, TopicPayload payload = TopicPayload.All); /// /// Loads a (and, optionally, all of its descendants) based on the specified —are integrated with existing entities. /// /// Determines whether or not to recurse through and load a topic's children. + /// + /// Specifies which data to include with each topic. See + /// for details. + /// /// A topic object. - Topic? Load(string uniqueKey, Topic? referenceTopic = null, bool isRecursive = true); + Topic? Load(string uniqueKey, Topic? referenceTopic = null, bool isRecursive = true, TopicPayload payload = TopicPayload.All); - /// + /// [ExcludeFromCodeCoverage] [Obsolete("This overload has been removed in preference for Load(string, Topic, Boolean).")] Topic? Load(string? uniqueKey, bool isRecursive); diff --git a/OnTopic/Repositories/ObservableTopicRepository.cs b/OnTopic/Repositories/ObservableTopicRepository.cs index c5d803fc..096fd6c8 100644 --- a/OnTopic/Repositories/ObservableTopicRepository.cs +++ b/OnTopic/Repositories/ObservableTopicRepository.cs @@ -212,12 +212,22 @@ public event EventHandler? TopicRenamed { public virtual Topic? Load() => Load(-1); /// - public abstract Topic? Load(int topicId, Topic? referenceTopic = null, bool isRecursive = true); + public abstract Topic? Load( + int topicId, + Topic? referenceTopic = null, + bool isRecursive = true, + TopicPayload payload = TopicPayload.All + ); /// - public abstract Topic? Load(string uniqueKey, Topic? referenceTopic = null, bool isRecursive = true); - - /// + public abstract Topic? Load( + string uniqueKey, + Topic? referenceTopic = null, + bool isRecursive = true, + TopicPayload payload = TopicPayload.All + ); + + /// [ExcludeFromCodeCoverage] [Obsolete("This overload has been removed in preference for Load(string, Topic, Boolean).")] public Topic? Load(string? uniqueKey, bool isRecursive) => throw new NotImplementedException(); diff --git a/OnTopic/Repositories/TopicRepositoryDecorator.cs b/OnTopic/Repositories/TopicRepositoryDecorator.cs index 06eb5f0e..126fd587 100644 --- a/OnTopic/Repositories/TopicRepositoryDecorator.cs +++ b/OnTopic/Repositories/TopicRepositoryDecorator.cs @@ -80,12 +80,22 @@ protected TopicRepositoryDecorator(ITopicRepository topicRepository) : base() { public override Topic? Load() => Load(-1); /// - public override Topic? Load(int topicId, Topic? referenceTopic = null, bool isRecursive = true) => - TopicRepository.Load(topicId, referenceTopic, isRecursive); + public override Topic? Load( + int topicId, + Topic? referenceTopic = null, + bool isRecursive = true, + TopicPayload payload = TopicPayload.All + ) => + TopicRepository.Load(topicId, referenceTopic, isRecursive, payload); /// - public override Topic? Load(string uniqueKey, Topic? referenceTopic = null, bool isRecursive = true) => - TopicRepository.Load(uniqueKey, referenceTopic, isRecursive); + public override Topic? Load( + string uniqueKey, + Topic? referenceTopic = null, + bool isRecursive = true, + TopicPayload payload = TopicPayload.All + ) => + TopicRepository.Load(uniqueKey, referenceTopic, isRecursive, payload); /// public override Topic? Load(Topic topic, DateTime version) diff --git a/OnTopic/Repositories/_eventArgs/TopicLoadEventArgs.cs b/OnTopic/Repositories/_eventArgs/TopicLoadEventArgs.cs index f0b4fc93..8dead99e 100644 --- a/OnTopic/Repositories/_eventArgs/TopicLoadEventArgs.cs +++ b/OnTopic/Repositories/_eventArgs/TopicLoadEventArgs.cs @@ -19,7 +19,7 @@ public class TopicLoadEventArgs : TopicEventArgs { \---------------------------------------------------------------------------------------------------------------------------*/ /// /// The object defines the event arguments relevant to a operation and its overloads. + /// Load(Int32, Topic?, Boolean, TopicPayload)"/> operation and its overloads. /// /// The object associated with the rename event. /// Whether or not descendants of the were also loaded. From a05ff7002bd85a50b074b94259301353522a96ef Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 3 Jul 2026 15:29:41 -0700 Subject: [PATCH 031/337] Introduced basic unit tests for `Load()` overloads These don't currently do anything outside of verify that the new `TopicPayload` enum overload is accepted (58524089). As part of #111, we'll want to fill out the stub to better test the actual functionality later. --- OnTopic.Tests/TopicRepositoryBaseTest.cs | 35 ++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/OnTopic.Tests/TopicRepositoryBaseTest.cs b/OnTopic.Tests/TopicRepositoryBaseTest.cs index 6196c8c9..fe94ea4d 100644 --- a/OnTopic.Tests/TopicRepositoryBaseTest.cs +++ b/OnTopic.Tests/TopicRepositoryBaseTest.cs @@ -86,6 +86,41 @@ public void Load_InvalidTopicId_ReturnsExpectedTopic() => public void Load_NegativeTopicId_ReturnsRootTopic() => Assert.Equal("Root", _cachedTopicRepository.Load(-2)?.GetUniqueKey()); + /*============================================================================================================================ + | TEST: LOAD: NARROW PAYLOAD: RETURNS TOPIC + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Calls with payload set to and confirms that a topic is still returned. The stub always returns fully-loaded topics + /// regardless of this parameter; the test simply verifies the signature is accepted. + /// + [Fact] + public void Load_WithNarrowPayload_ReturnsTopic() { + + var topic = _topicRepository.Load(11111, payload: TopicPayload.None); + + Assert.NotNull(topic); + + } + + /*============================================================================================================================ + | TEST: LOAD: NARROW PAYLOAD: EXTENDED ATTRIBUTES LOADED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Calls with payload set to and confirms the extended-attribute boundary is . The stub does not + /// defer extended attributes; this simply confirms no regression for stub-backed tests. + /// + [Fact] + public void Load_WithNarrowPayload_ExtendedAttributesLoaded() { + + var topic = _topicRepository.Load(11111, payload: TopicPayload.None); + + Assert.NotNull(topic); + Assert.Equal(LoadState.Loaded, topic.Attributes.LoadState); + + } + /*============================================================================================================================ | TEST: LOAD: VALID DATE: RETURNS TOPIC \---------------------------------------------------------------------------------------------------------------------------*/ From 5ca272d268977b6e6470e3ca38afa15c4c35917b Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 3 Jul 2026 16:32:29 -0700 Subject: [PATCH 032/337] Removed relations from `MarkBoundariesLoaded()` When `MarkBoundariesLoaded()` was initially introduced (de60afb4) as part of the integration of `LoadBoundaries` (now `TopicPayload`; 07a01cf8), it set the `LoadState` for both `Relationships` and `References`. This was a mistake, however, since a partial Topic graph won't have all matching nodes. As a result, when `SetRelationships()` and `SetReferences()` run (a013fe06) they set `LoadState.NotLoaded` if any items are orphaned. This still doesn't ensure that these are marked as `NotLoaded` if they're actually not loaded, so we'll need to circle back to that in a future commit. --- OnTopic.Data.Sql/SqlTopicRepository.cs | 24 +++++++++++------------- 1 file changed, 11 insertions(+), 13 deletions(-) diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index 15cc9bbb..e8ca0da6 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -849,26 +849,24 @@ protected override sealed void DeleteTopic(Topic topic) { | METHOD: MARK BOUNDARIES LOADED \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Marks each boundary in as on the given - /// after a successful resolver fill. + /// Marks each boundary in as on the given after a successful resolver fill. /// + /// + /// and are intentionally excluded. Their + /// is set by and based on whether each target is resident in the topic graph: a non-resident + /// target sets , which blocks DeleteUnmatched on save and prevents silent data + /// loss. Overwriting that state here, before the resolver has access to the live graph, would defeat that guard. + /// private static void MarkBoundariesLoaded(Topic topic, TopicPayload boundaries) { - // Extended attributes + // Extended attributes: Mark Loaded unconditionally; the whole blob is fetched as a unit and is complete regardless of + // whether related topics are resident if (boundaries.HasFlag(TopicPayload.ExtendedAttributes)) { topic.Attributes.LoadState = LoadState.Loaded; } - // Relationships - if (boundaries.HasFlag(TopicPayload.Relationships)) { - topic.Relationships.LoadState = LoadState.Loaded; - } - - // References - if (boundaries.HasFlag(TopicPayload.References)) { - topic.References.LoadState = LoadState.Loaded; - } - } /*============================================================================================================================ From 6bf76506d9efde801d54ee6ebb4bab0f782c69b9 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 3 Jul 2026 16:36:40 -0700 Subject: [PATCH 033/337] Add `Relationships`, `Related` to stub repository These will be needed in subsequent unit tests. For now, as with the previously committed `ExtendedAttribute` stub (e25f8431), this doesn't really do anything yet, as it doesn't conditionally return relationships; that will need to be addressed in a subsequent update. This contributes to the testing of #111. --- OnTopic.TestDoubles/StubTopicRepository.cs | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/OnTopic.TestDoubles/StubTopicRepository.cs b/OnTopic.TestDoubles/StubTopicRepository.cs index 9cc2e05e..c8994638 100644 --- a/OnTopic.TestDoubles/StubTopicRepository.cs +++ b/OnTopic.TestDoubles/StubTopicRepository.cs @@ -216,12 +216,21 @@ public virtual void EnsureLoaded(Topic topic, TopicPayload boundaries) { Contract.Requires(topic); /*-------------------------------------------------------------------------------------------------------------------------- - | Mark extended attribute boundary as loaded; this is a no-op for children, as it's already populated in the stubs + | Mark boundaries as loaded; stubs have all relationships and references pre-built in memory, so all targets are resident + | and marking Loaded is always safe. Children is already populated in the stubs and needs no action. \-------------------------------------------------------------------------------------------------------------------------*/ if (boundaries.HasFlag(TopicPayload.ExtendedAttributes) && topic.Attributes.LoadState is LoadState.NotLoaded) { topic.Attributes.LoadState = LoadState.Loaded; } + if (boundaries.HasFlag(TopicPayload.Relationships) && topic.Relationships.LoadState is LoadState.NotLoaded) { + topic.Relationships.LoadState = LoadState.Loaded; + } + + if (boundaries.HasFlag(TopicPayload.References) && topic.References.LoadState is LoadState.NotLoaded) { + topic.References.LoadState = LoadState.Loaded; + } + } /// From d7c81d6cee378646680f826dd0a54d3475e0fcda Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 3 Jul 2026 16:44:43 -0700 Subject: [PATCH 034/337] Add initial unit tests for lazy-loading relations This utilizes the updated `StubTopicRepository` (6bf76506) to add unit tests for confirming that the `LoadState` is correct on both `Relationships` and `References` based on whether the referenced Topic.Id is or is not present in the topic graph. This contributes to testing of #111, though we'll need to make this more sophisticated once we have fully wired up the relations. --- OnTopic.Tests/SqlTopicRepositoryTest.cs | 108 +++++++++++++++++++++++ OnTopic.Tests/TopicRepositoryBaseTest.cs | 41 +++++++++ 2 files changed, 149 insertions(+) diff --git a/OnTopic.Tests/SqlTopicRepositoryTest.cs b/OnTopic.Tests/SqlTopicRepositoryTest.cs index d9fbf683..f19b9dcb 100644 --- a/OnTopic.Tests/SqlTopicRepositoryTest.cs +++ b/OnTopic.Tests/SqlTopicRepositoryTest.cs @@ -335,7 +335,115 @@ public void LoadTopicGraph_WithDeletedRelationship_RemovesRelationship() { } + /*============================================================================================================================ + | TEST: LOAD TOPIC GRAPH: INDEXED-ONLY WITH RELATIONSHIP: RETURNS LOADED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Calls under an indexed-only + /// load (i.e., extended attributes deferred via HasExtendedAttributes = true) with a relationship whose target is + /// resident, and confirms that returns . + /// + [Fact] + public void LoadTopicGraph_IndexedOnlyWithRelationship_ReturnsLoaded() { + + using var topics = new TopicsDataTable(); + using var empty = new AttributesDataTable(); + using var relationships = new RelationshipsDataTable(); + + topics.AddRow(1, "Root", "Container", null, hasExtendedAttributes: true); + topics.AddRow(2, "Web", "Container", 1, hasExtendedAttributes: false); + relationships.AddRow(1, "Test", 2, false); + + using var tableReader = new DataTableReader(new DataTable[] { topics, empty, empty, relationships }); + + var topic = tableReader.LoadTopicGraph(); + + Assert.NotNull(topic); + Assert.Equal(LoadState.Loaded, topic?.Relationships.LoadState); + + } + /*============================================================================================================================ + | TEST: LOAD TOPIC GRAPH: INDEXED-ONLY WITH MISSING RELATIONSHIP: RETURNS NOT LOADED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Calls under an indexed-only + /// load with a relationship whose target is non-resident, and confirms that returns . + /// + [Fact] + public void LoadTopicGraph_IndexedOnlyWithMissingRelationship_ReturnsNotLoaded() { + + using var topics = new TopicsDataTable(); + using var empty = new AttributesDataTable(); + using var relationships = new RelationshipsDataTable(); + + topics.AddRow(1, "Root", "Container", null, hasExtendedAttributes: true); + relationships.AddRow(1, "Test", 99, false); + + using var tableReader = new DataTableReader(new DataTable[] { topics, empty, empty, relationships }); + + var topic = tableReader.LoadTopicGraph(); + + Assert.NotNull(topic); + Assert.Equal(LoadState.NotLoaded, topic!.Relationships.LoadState); + + } + + /*============================================================================================================================ + | TEST: LOAD TOPIC GRAPH: INDEXED-ONLY WITH REFERENCE: RETURNS LOADED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Calls under an indexed-only + /// load with a reference whose target is resident, and confirms that + /// returns . + /// + [Fact] + public void LoadTopicGraph_IndexedOnlyWithReference_ReturnsLoaded() { + + using var topics = new TopicsDataTable(); + using var empty = new AttributesDataTable(); + using var references = new TopicReferencesDataTable(); + + topics.AddRow(1, "Root", "Container", null, hasExtendedAttributes: true); + topics.AddRow(2, "Web", "Container", 1, hasExtendedAttributes: false); + references.AddRow(1, "Test", 2); + + using var tableReader = new DataTableReader(new DataTable[] { topics, empty, empty, empty, references }); + + var topic = tableReader.LoadTopicGraph(); + + Assert.NotNull(topic); + Assert.Equal(LoadState.Loaded, topic?.References.LoadState); + + } + + /*============================================================================================================================ + | TEST: LOAD TOPIC GRAPH: INDEXED-ONLY WITH MISSING REFERENCE: RETURNS NOT LOADED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Calls under an indexed-only + /// load with a reference whose target is non-resident, and confirms that + /// returns . + /// + [Fact] + public void LoadTopicGraph_IndexedOnlyWithMissingReference_ReturnsNotLoaded() { + + using var topics = new TopicsDataTable(); + using var empty = new AttributesDataTable(); + using var references = new TopicReferencesDataTable(); + + topics.AddRow(1, "Root", "Container", null, hasExtendedAttributes: true); + references.AddRow(1, "Test", 99); + + using var tableReader = new DataTableReader(new DataTable[] { topics, empty, empty, empty, references }); + + var topic = tableReader.LoadTopicGraph(); + + Assert.NotNull(topic); + Assert.Equal(LoadState.NotLoaded, topic!.References.LoadState); + + } /*============================================================================================================================ | TEST: LOAD TOPIC GRAPH: WITH VERSION HISTORY: RETURNS VERSIONS diff --git a/OnTopic.Tests/TopicRepositoryBaseTest.cs b/OnTopic.Tests/TopicRepositoryBaseTest.cs index fe94ea4d..0a3d05d5 100644 --- a/OnTopic.Tests/TopicRepositoryBaseTest.cs +++ b/OnTopic.Tests/TopicRepositoryBaseTest.cs @@ -1196,6 +1196,47 @@ public void EnsureLoaded_MixedBoundaries_SkipsLoadedBoundaries() { } + /*============================================================================================================================ + | TEST: ENSURE LOADED: RELATIONSHIPS NOT LOADED: MARKS LOADED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Loads a whose relationship boundary has been manually set to + /// and confirms that promotes the boundary to via the 's fill. + /// + /// + [Fact] + public void EnsureLoaded_RelationshipsNotLoaded_MarksLoaded() { + + var topic = _topicRepository.Load(11111); + + topic!.Relationships.LoadState = LoadState.NotLoaded; + topic.EnsureLoaded(TopicPayload.Relationships); + + Assert.True(topic.IsLoaded(TopicPayload.Relationships)); + + } + + /*============================================================================================================================ + | TEST: ENSURE LOADED: REFERENCES NOT LOADED: MARKS LOADED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Loads a whose reference boundary has been manually set to and + /// confirms that promotes the boundary to + /// via the 's fill. + /// + [Fact] + public void EnsureLoaded_ReferencesNotLoaded_MarksLoaded() { + + var topic = _topicRepository.Load(11111); + + topic!.References.LoadState = LoadState.NotLoaded; + topic.EnsureLoaded(TopicPayload.References); + + Assert.True(topic.IsLoaded(TopicPayload.References)); + + } + /*============================================================================================================================ | TEST: MOVE: TOPIC MOVED EVENT: IS RAISED \---------------------------------------------------------------------------------------------------------------------------*/ From d19637ea16548beda130fac8c7ef9b5b4c34d7d9 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 3 Jul 2026 16:46:08 -0700 Subject: [PATCH 035/337] Fixed formatting error in XML Doc This was inadvertently introduced in a previous update when I was adding the `TopicPayload` to the `ITopicRepository.Load()` signature (58524089). --- OnTopic/Collections/Specialized/TrackedRecord{T}.cs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/OnTopic/Collections/Specialized/TrackedRecord{T}.cs b/OnTopic/Collections/Specialized/TrackedRecord{T}.cs index 250a51dc..b1758a3a 100644 --- a/OnTopic/Collections/Specialized/TrackedRecord{T}.cs +++ b/OnTopic/Collections/Specialized/TrackedRecord{T}.cs @@ -105,8 +105,8 @@ protected TrackedRecord(string key, T? value, bool isDirty = true, DateTime? las /// If loaded from a data store from e.g. , the /// should be set to the Version. If the is novel, however, then it /// should be set to the current date. That won't be the same date established by for the Version, however, which is why this property is labeled . + /// "ITopicRepository.Save(Topic, Boolean)"/> for the Version, however, which is why this property is labeled . /// public DateTime LastModified { get; init; } From 9c91f295fbd6d8c16c2cb5ab0ce770459346ddf6 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 3 Jul 2026 20:11:47 -0700 Subject: [PATCH 036/337] Support composable graph in `GetTopics` sproc On the `GetTopics` stored procedure, we previously replaced `@DeepLoad` with a bidirectional option of `@LoadAscendants` and `@LoadDescendants` (8c2c81da), but only allowed loading one of them. This allows both to be loaded, while also adding support for `@HasChildren` (if `@HasDescendants` isn't already selected, as otherwise it's implicit). In practice, it's likely that callers will only want one of them, but this lifts that artificial constraint while allowing callers more flexibility. In practice, this flexibility will likely live exclusively in the `SqlTopicRepository`, which should request `@LoadAscendants` if it doesn't otherwise know where in an existing topic graph a topic it's requesting is situated, regardless of whether it's also getting the children or descendants. This contributes to the lazy-loading project (#111). --- .../Stored Procedures/GetTopics.sql | 37 +++++++++++++++++-- 1 file changed, 34 insertions(+), 3 deletions(-) diff --git a/OnTopic.Data.Sql.Database/Stored Procedures/GetTopics.sql b/OnTopic.Data.Sql.Database/Stored Procedures/GetTopics.sql index 30a6e2f6..00352f3b 100644 --- a/OnTopic.Data.Sql.Database/Stored Procedures/GetTopics.sql +++ b/OnTopic.Data.Sql.Database/Stored Procedures/GetTopics.sql @@ -9,6 +9,7 @@ CREATE PROCEDURE [dbo].[GetTopics] @TopicID INT = -1, @LoadDescendants BIT = 1, @LoadAscendants BIT = 0, + @LoadChildren BIT = 0, @IncludeIndexed BIT = 1, @IncludeExtended BIT = 1, @IncludeRelationships BIT = 1, @@ -70,13 +71,38 @@ IF @LoadDescendants = 1 ) END +-------------------------------------------------------------------------------------------------------------------------------- +-- SELECT IMMEDIATE CHILDREN +-------------------------------------------------------------------------------------------------------------------------------- +-- Loads only the direct children of the requested topic. Mutually exclusive with LoadDescendants, as loading children of a +-- subtree that is already being loaded is redundant. +-------------------------------------------------------------------------------------------------------------------------------- +ELSE IF @LoadChildren = 1 + BEGIN + INSERT #Topics ( + TopicID, + SortOrder + ) + SELECT T1.TopicID, + T1.RangeLeft + FROM Topics AS T1 + WHERE T1.ParentID = @TopicID + ORDER BY T1.RangeLeft + OPTION ( + OPTIMIZE + FOR ( @TopicID UNKNOWN + ) + ) + END + -------------------------------------------------------------------------------------------------------------------------------- -- SELECT TOPIC AND ANCESTOR CHAIN -------------------------------------------------------------------------------------------------------------------------------- -- Ancestors are rows whose nested-set range contains the requested node's RangeLeft, i.e., the mirror of the descendant query --- above. This guarantees the full parent chain is always materialized, even on a shallow (non-recursive) load. +-- above. This can be combined with LoadDescendants to load both the subtree and its ancestor chain in a single query. The NOT +-- EXISTS guard prevents duplicate inserts when both are requested. -------------------------------------------------------------------------------------------------------------------------------- -ELSE IF @LoadAscendants = 1 +IF @LoadAscendants = 1 BEGIN INSERT #Topics ( TopicID, @@ -90,6 +116,11 @@ ELSE IF @LoadAscendants = 1 BETWEEN T1.RangeLeft AND T1.RangeRight AND T2.TopicID = @TopicID + WHERE NOT EXISTS ( + SELECT 1 + FROM #Topics + WHERE TopicID = T1.TopicID + ) ORDER BY T1.RangeLeft OPTION ( OPTIMIZE @@ -104,7 +135,7 @@ ELSE IF @LoadAscendants = 1 -- Inserts only the requested topic; used by the lazy-load resolver to fill a single topic's extended attributes without -- traversing the tree in either direction. -------------------------------------------------------------------------------------------------------------------------------- -ELSE +IF @LoadDescendants = 0 AND @LoadChildren = 0 AND @LoadAscendants = 0 BEGIN INSERT #Topics ( TopicID, From e3e7cfbafa16b5495b478d5c11bf0a4e120c1ea2 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 3 Jul 2026 23:16:27 -0700 Subject: [PATCH 037/337] Introduced `HasChildren` column to `GetTopics` This uses a basic range check on the nested set to determine if the current topic has children. This will be used by `LoadTopicGraph()` to determine if the `Topic.Children.LoadState` should be set to `NotLoaded` or to `Loaded`. I.e., even if `@LoadDescendants` isn't true, if `HasChildren` is false, then we know the `Children.LoadState` is `Loaded`, since there aren't any further children to retrieve. This will require care of `@LoadAncestors` is included as the ancestors of the `@TopicId` will all have `HasChildren` set to true, and all will have a child returned, but that doesn't mean _all_ of their children are loaded. For those cases, the `LoadTopicGraph()` should assume `NotLoaded` to be safe. This correspond in purpose to `HasExtendedAttributes` (9475ec3e), which was previously introduced, though this is a cheaper check. This contributes to the lazy-loading project (#111) by allowing us to detect the `LoadState` of children and, therefore, whether they need to lazy-loaded in the future. --- .../Stored Procedures/GetTopics.sql | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/OnTopic.Data.Sql.Database/Stored Procedures/GetTopics.sql b/OnTopic.Data.Sql.Database/Stored Procedures/GetTopics.sql index 00352f3b..01b41c42 100644 --- a/OnTopic.Data.Sql.Database/Stored Procedures/GetTopics.sql +++ b/OnTopic.Data.Sql.Database/Stored Procedures/GetTopics.sql @@ -153,9 +153,16 @@ SELECT Topics.TopicID, ParentID, TopicKey, SortOrder, + HasChildren = CAST( + CASE + WHEN Topics.RangeRight - Topics.RangeLeft > 1 + THEN 1 + ELSE 0 + END AS BIT + ), HasExtendedAttributes = CASE - WHEN @IncludeExtended = 0 + WHEN @IncludeExtended = 0 THEN CAST( CASE WHEN EXISTS ( From 8be260e7e9e0e04d4c71b8387c5aeaf666419de3 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 3 Jul 2026 23:18:35 -0700 Subject: [PATCH 038/337] Backfill `HasExtendedAttributes`, `HasChildren` Backfilled `HasExtendedAttributes` (9475ec3e) and `HasChildren` (e3e7cfba) to the `GetTopicUpdates` and `GetTopicVersion` stored procedures, so the return is the same shape, and thus remains compatible with the expectations of e.g., `LoadTopicGraph()`, though these just return `null` as the nature of these stored procedures is that children simply relevant. (In `GetTopicUpdates`, we're just getting one-off attributes for topics that already exist; in `GetTopicVersion`, it's specifically reviewing an individual topic version; versioning doesn't encapsulate the tree.) This contributes to #111. --- .../Stored Procedures/GetTopicUpdates.sql | 4 +++- .../Stored Procedures/GetTopicVersion.sql | 4 +++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/OnTopic.Data.Sql.Database/Stored Procedures/GetTopicUpdates.sql b/OnTopic.Data.Sql.Database/Stored Procedures/GetTopicUpdates.sql index 98bba426..b6f1c89a 100644 --- a/OnTopic.Data.Sql.Database/Stored Procedures/GetTopicUpdates.sql +++ b/OnTopic.Data.Sql.Database/Stored Procedures/GetTopicUpdates.sql @@ -15,7 +15,9 @@ SELECT TopicID, ContentType, ParentID, TopicKey, - 0 AS SortOrder + 0 AS SortOrder, + HasChildren = NULL, + HasExtendedAttributes = NULL FROM Topics WHERE LastModified > @Since diff --git a/OnTopic.Data.Sql.Database/Stored Procedures/GetTopicVersion.sql b/OnTopic.Data.Sql.Database/Stored Procedures/GetTopicVersion.sql index 0b37a0c8..7014cc32 100644 --- a/OnTopic.Data.Sql.Database/Stored Procedures/GetTopicVersion.sql +++ b/OnTopic.Data.Sql.Database/Stored Procedures/GetTopicVersion.sql @@ -20,7 +20,9 @@ SELECT TopicID, ContentType, ParentID, TopicKey, - 0 AS SortOrder + 0 AS SortOrder, + HasChildren = NULL, + HasExtendedAttributes = NULL FROM Topics WHERE TopicID = @TopicID From 78602c2bfd1ac80818512425a3c5567cf15b1159 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 3 Jul 2026 23:19:57 -0700 Subject: [PATCH 039/337] Added `HasChildren` column to `TopicsDataTable` This adds the new `HasChildren` column (e3e7cfba) to the `TopicsDataTable` to support testing of #111. This corresponds to the previous addition of `HasExtendedAttributes` (5e4f923e). --- OnTopic.Tests/Schemas/TopicsDataTable.cs | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/OnTopic.Tests/Schemas/TopicsDataTable.cs b/OnTopic.Tests/Schemas/TopicsDataTable.cs index 9fbc4ad3..d91d93cd 100644 --- a/OnTopic.Tests/Schemas/TopicsDataTable.cs +++ b/OnTopic.Tests/Schemas/TopicsDataTable.cs @@ -63,6 +63,15 @@ public TopicsDataTable() : base("Topics") { AllowDBNull = true }); + /*-------------------------------------------------------------------------------------------------------------------------- + | Add HasChildren column + \-------------------------------------------------------------------------------------------------------------------------*/ + Columns.Add(new DataColumn() { + DataType = typeof(bool), + ColumnName = "HasChildren", + AllowDBNull = true + }); + /*-------------------------------------------------------------------------------------------------------------------------- | Add HasExtendedAttributes column \-------------------------------------------------------------------------------------------------------------------------*/ @@ -85,6 +94,7 @@ public void AddRow( string topicKey, string contentType, int? parentId = null, + bool? hasChildren = null, bool? hasExtendedAttributes = null ) { @@ -104,6 +114,7 @@ public void AddRow( row["TopicKey"] = topicKey; row["ContentType"] = contentType; row["ParentId"] = parentId.HasValue? parentId : DBNull.Value; + row["HasChildren"] = hasChildren.HasValue? hasChildren.Value : DBNull.Value; row["HasExtendedAttributes"] = hasExtendedAttributes.HasValue? hasExtendedAttributes.Value : DBNull.Value; /*-------------------------------------------------------------------------------------------------------------------------- From 5f92c5f612968e36756ccb05b21b449512ddb2d9 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sat, 4 Jul 2026 01:08:30 -0700 Subject: [PATCH 040/337] Added new `seedTopicId` to `LoadTopicGraph()` The new `seedTopicId` parameter isn't utilized yet, but will be used in a subsequent update to differentiate between the topic that was requested to be loaded, if any, and any ancestors that that were loaded via `@LoadAncendants` (de60afb4). This is necessary because a) we know all ancestors have children (and thus `HasChildren`; e3e7cfba), BUT we don't know if ALL of their children have been loaded. By knowing the `seedTopicId` we can identify any parents of the topic that were returned, but don't already exist in the graph, and mark their children as `NotLoaded`. This includes updating all calls to `LoadTopicGraph()` to include the `seedTopicId`, if they have one. This will exist in most cases this logic is relevant, but won't exist when loading the entire topic graph or, at least, just the root node. Putting `seedTopicId` first makes sense for most callers, but not for our test cases, most of which have a `referenceTopic` but not a `topicId`. As such, their signatures had to be updated to include `referenceTopicId:` since it's not the first parameter. That said, while I was at it, I removed the full signature from the XML Doc references since there aren't any overloads, which dramatically simplifies their references. This is part of #111. --- OnTopic.Data.Sql/SqlDataReaderExtensions.cs | 7 ++ OnTopic.Data.Sql/SqlTopicRepository.cs | 10 +- OnTopic.Tests/SqlTopicRepositoryTest.cs | 105 ++++++++++---------- 3 files changed, 64 insertions(+), 58 deletions(-) diff --git a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs index c287b291..e6fd1fd5 100644 --- a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs +++ b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs @@ -36,6 +36,12 @@ internal static class SqlDataReaderExtensions { /// topics and populate their attributes, associations, and children. /// /// The with output from the GetTopics stored procedure. + /// + /// The that was passed to the underlying query (i.e., the root of the requested subtree or the topic + /// whose ancestors were requested). Used to identify which newly loaded topics are ancestors so that their can be correctly stamped as . The default is -1, which + /// applies when the root was loaded, or when no single seed applies (e.g., the GetTopicUpdates path). + /// /// /// When loading a single topic or branch, offers a reference topic graph that can be used to ensure that topic /// associations—such as references, relationships, and —are integrated with existing entities. @@ -53,6 +59,7 @@ internal static class SqlDataReaderExtensions { /// internal static Topic? LoadTopicGraph( this IDataReader reader, + int seedTopicId = -1, Topic? referenceTopic = null, bool? markDirty = null, bool includeExternalReferences = true diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index e8ca0da6..5d4c8c8d 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -152,7 +152,7 @@ public override Topic Load( try { connection.Open(); using var reader = command.ExecuteReader(); - topic = reader.LoadTopicGraph(referenceTopic, false); + topic = reader.LoadTopicGraph(topicId, referenceTopic, false); } /*-------------------------------------------------------------------------------------------------------------------------- @@ -264,7 +264,11 @@ public override Topic Load(int topicId, DateTime version, Topic? referenceTopic try { connection.Open(); using var reader = command.ExecuteReader(); - topic = reader.LoadTopicGraph(referenceTopic, includeExternalReferences: referenceTopic is not null); + topic = reader.LoadTopicGraph( + topicId, + referenceTopic, + includeExternalReferences: referenceTopic is not null + ); } /*-------------------------------------------------------------------------------------------------------------------------- @@ -357,7 +361,7 @@ public override void Refresh(Topic referenceTopic, DateTime since) { try { connection.Open(); using var reader = command.ExecuteReader(); - reader.LoadTopicGraph(referenceTopic.GetRootTopic(), false); + reader.LoadTopicGraph(-1, referenceTopic.GetRootTopic(), false); } /*-------------------------------------------------------------------------------------------------------------------------- diff --git a/OnTopic.Tests/SqlTopicRepositoryTest.cs b/OnTopic.Tests/SqlTopicRepositoryTest.cs index f19b9dcb..17b10c99 100644 --- a/OnTopic.Tests/SqlTopicRepositoryTest.cs +++ b/OnTopic.Tests/SqlTopicRepositoryTest.cs @@ -26,8 +26,8 @@ public class SqlTopicRepositoryTest { | TEST: LOAD TOPIC GRAPH: WITH TOPIC: RETURNS TOPIC \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Calls with a record and confirms that a topic with those values is returned. + /// Calls with a record and confirms that + /// a topic with those values is returned. /// [Fact] public void LoadTopicGraph_WithTopic_ReturnsTopic() { @@ -49,9 +49,8 @@ public void LoadTopicGraph_WithTopic_ReturnsTopic() { | TEST: LOAD TOPIC GRAPH: WITH NEW PARENT: UPDATES PARENT \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Calls with a record that represents a different parent than the existing referenceTopic and confirms that - /// the topic's parent is updated. + /// Calls with a record that represents a + /// different parent than the existing referenceTopic and confirms that the topic's parent is updated. /// [Fact] public void LoadTopicGraph_WithNewParent_UpdatesParent() { @@ -67,7 +66,7 @@ public void LoadTopicGraph_WithNewParent_UpdatesParent() { using var tableReader = new DataTableReader(topics); - tableReader.LoadTopicGraph(topic); + tableReader.LoadTopicGraph(referenceTopic: topic); Assert.Equal(parent2, child.Parent); @@ -77,8 +76,8 @@ public void LoadTopicGraph_WithNewParent_UpdatesParent() { | TEST: LOAD TOPIC GRAPH: WITH ATTRIBUTES: RETURNS ATTRIBUTES \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Calls with an record and confirms that a topic with those values is returned. + /// Calls with an record and confirms + /// that a topic with those values is returned. /// [Fact] public void LoadTopicGraph_WithAttributes_ReturnsAttributes() { @@ -103,9 +102,8 @@ public void LoadTopicGraph_WithAttributes_ReturnsAttributes() { | TEST: LOAD TOPIC GRAPH: WITH NULL ATTRIBUTES: REMOVES ATTRIBUTE \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Calls with an record representing a deleted attribute and confirms that an existing reference topic with that - /// attribute has the value removed. + /// Calls with an record representing + /// a deleted attribute and confirms that an existing reference topic with that attribute has the value removed. /// [Fact] public void LoadTopicGraph_WithNullAttributes_RemovesAttribute() { @@ -122,7 +120,7 @@ public void LoadTopicGraph_WithNullAttributes_RemovesAttribute() { using var tableReader = new DataTableReader(new DataTable[] { topics, attributes }); - tableReader.LoadTopicGraph(topic); + tableReader.LoadTopicGraph(referenceTopic: topic); Assert.Null(topic.Attributes.GetValue("Test")); @@ -132,8 +130,8 @@ public void LoadTopicGraph_WithNullAttributes_RemovesAttribute() { | TEST: LOAD TOPIC GRAPH: WITH RELATIONSHIP: RETURNS RELATIONSHIP \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Calls with a record and confirms that a topic with those values is returned. + /// Calls with a record and + /// confirms that a topic with those values is returned. /// [Fact] public void LoadTopicGraph_WithRelationship_ReturnsRelationship() { @@ -161,9 +159,8 @@ public void LoadTopicGraph_WithRelationship_ReturnsRelationship() { | TEST: LOAD TOPIC GRAPH: WITH MISSING RELATIONSHIP: NOT FULLY LOADED \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Calls with a record that is missing and confirms that - /// returns . + /// Calls with a record that is + /// missing and confirms that returns . /// [Fact] public void LoadTopicGraph_WithMissingRelationship_NotFullyLoaded() { @@ -190,8 +187,8 @@ public void LoadTopicGraph_WithMissingRelationship_NotFullyLoaded() { | TEST: LOAD TOPIC GRAPH: WITH REFERENCE: RETURNS REFERENCE \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Calls with a record and confirms that a topic with those values is returned. + /// Calls with a record and + /// confirms that a topic with those values is returned. /// [Fact] public void LoadTopicGraph_WithReference_ReturnsReference() { @@ -219,8 +216,8 @@ public void LoadTopicGraph_WithReference_ReturnsReference() { | TEST: LOAD TOPIC GRAPH: WITH EXTERNAL REFERENCE: RETURNS REFERENCE \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Calls with a record and confirms that a topic with those values is returned. + /// Calls with a record and + /// confirms that a topic with those values is returned. /// [Fact] public void LoadTopicGraph_WithExternalReference_ReturnsReference() { @@ -236,7 +233,7 @@ public void LoadTopicGraph_WithExternalReference_ReturnsReference() { using var tableReader = new DataTableReader(new DataTable[] { topics, empty, empty, empty, references }); - var topic = tableReader.LoadTopicGraph(referenceTopic, false); + var topic = tableReader.LoadTopicGraph(1, referenceTopic, false); Assert.NotNull(topic); Assert.Equal(1, topic?.Id); @@ -250,9 +247,9 @@ public void LoadTopicGraph_WithExternalReference_ReturnsReference() { | TEST: LOAD TOPIC GRAPH: WITH DELETED REFERENCE: REMOVES EXISTING REFERENCE \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Calls with a record and confirms that existing references on a reference topic are deleted if they are - /// null in the . + /// Calls with a record and + /// confirms that existing references on a reference topic are deleted if they are null in the . /// [Fact] public void LoadTopicGraph_WithDeletedReference_RemovesExistingReference() { @@ -270,7 +267,7 @@ public void LoadTopicGraph_WithDeletedReference_RemovesExistingReference() { using var tableReader = new DataTableReader(new DataTable[] { topics, empty, empty, empty, references }); - tableReader.LoadTopicGraph(referenceTopic, false); + tableReader.LoadTopicGraph(1, referenceTopic, false); Assert.Null(referenceTopic.References.GetValue("Reference")); Assert.Equal(LoadState.Loaded, referenceTopic.References.LoadState); @@ -281,9 +278,8 @@ public void LoadTopicGraph_WithDeletedReference_RemovesExistingReference() { | TEST: LOAD TOPIC GRAPH: WITH MISSING REFERENCE: NOT FULLY LOADED \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Calls with a record that is missing and confirms that - /// returns . + /// Calls with a record that is + /// missing and confirms that returns . /// [Fact] public void LoadTopicGraph_WithMissingReference_NotFullyLoaded() { @@ -310,8 +306,8 @@ public void LoadTopicGraph_WithMissingReference_NotFullyLoaded() { | TEST: LOAD TOPIC GRAPH: WITH DELETED RELATIONSHIP: REMOVES RELATIONSHIP \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Calls with a deleted record and confirms that it is deleted from the referenceTopic graph. + /// Calls with a deleted record + /// and confirms that it is deleted from the referenceTopic graph. /// [Fact] public void LoadTopicGraph_WithDeletedRelationship_RemovesRelationship() { @@ -329,7 +325,7 @@ public void LoadTopicGraph_WithDeletedRelationship_RemovesRelationship() { using var tableReader = new DataTableReader(new DataTable[] { empty, empty, empty, relationships }); - tableReader.LoadTopicGraph(related); + tableReader.LoadTopicGraph(referenceTopic: related); Assert.Empty(topic.Relationships.GetValues("Test")); @@ -339,9 +335,9 @@ public void LoadTopicGraph_WithDeletedRelationship_RemovesRelationship() { | TEST: LOAD TOPIC GRAPH: INDEXED-ONLY WITH RELATIONSHIP: RETURNS LOADED \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Calls under an indexed-only - /// load (i.e., extended attributes deferred via HasExtendedAttributes = true) with a relationship whose target is - /// resident, and confirms that returns . + /// Calls under an indexed-only load (i.e., extended attributes + /// deferred via HasExtendedAttributes = true) with a relationship whose target is resident, and confirms that + /// returns . /// [Fact] public void LoadTopicGraph_IndexedOnlyWithRelationship_ReturnsLoaded() { @@ -367,9 +363,9 @@ public void LoadTopicGraph_IndexedOnlyWithRelationship_ReturnsLoaded() { | TEST: LOAD TOPIC GRAPH: INDEXED-ONLY WITH MISSING RELATIONSHIP: RETURNS NOT LOADED \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Calls under an indexed-only - /// load with a relationship whose target is non-resident, and confirms that returns . + /// Calls under an indexed-only load with a relationship whose target is + /// non-resident, and confirms that returns . /// [Fact] public void LoadTopicGraph_IndexedOnlyWithMissingRelationship_ReturnsNotLoaded() { @@ -394,9 +390,8 @@ public void LoadTopicGraph_IndexedOnlyWithMissingRelationship_ReturnsNotLoaded() | TEST: LOAD TOPIC GRAPH: INDEXED-ONLY WITH REFERENCE: RETURNS LOADED \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Calls under an indexed-only - /// load with a reference whose target is resident, and confirms that - /// returns . + /// Calls under an indexed-only load with a reference whose target is + /// resident, and confirms that returns . /// [Fact] public void LoadTopicGraph_IndexedOnlyWithReference_ReturnsLoaded() { @@ -422,9 +417,9 @@ public void LoadTopicGraph_IndexedOnlyWithReference_ReturnsLoaded() { | TEST: LOAD TOPIC GRAPH: INDEXED-ONLY WITH MISSING REFERENCE: RETURNS NOT LOADED \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Calls under an indexed-only - /// load with a reference whose target is non-resident, and confirms that - /// returns . + /// Calls under an indexed-only load with a reference whose target is + /// non-resident, and confirms that returns . /// [Fact] public void LoadTopicGraph_IndexedOnlyWithMissingReference_ReturnsNotLoaded() { @@ -449,8 +444,8 @@ public void LoadTopicGraph_IndexedOnlyWithMissingReference_ReturnsNotLoaded() { | TEST: LOAD TOPIC GRAPH: WITH VERSION HISTORY: RETURNS VERSIONS \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Calls with an record and confirms that a topic with those values is returned. + /// Calls with an record and + /// confirms that a topic with those values is returned. /// [Fact] public void LoadTopicGraph_WithVersionHistory_ReturnsVersions() { @@ -477,9 +472,9 @@ public void LoadTopicGraph_WithVersionHistory_ReturnsVersions() { | TEST: LOAD TOPIC GRAPH: WITH EXTENDED DEFERRED AND BLOB: RETURNS NOT LOADED \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Calls with a row where HasExtendedAttributes is (blob deferred), and confirms the - /// extended-attribute boundary is . + /// Calls with a row where + /// HasExtendedAttributes is (blob deferred), and confirms the extended-attribute boundary is + /// . /// [Fact] public void LoadTopicGraph_WithExtendedDeferredAndBlob_ReturnsNotLoaded() { @@ -501,9 +496,9 @@ public void LoadTopicGraph_WithExtendedDeferredAndBlob_ReturnsNotLoaded() { | TEST: LOAD TOPIC GRAPH: WITH EXTENDED DEFERRED AND NO BLOB: RETURNS LOADED \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Calls with a row where HasExtendedAttributes is (blob deferred, but empty), and - /// confirms the extended-attribute boundary is , thus avoiding a wasted round-trip. + /// Calls with a row where + /// HasExtendedAttributes is (blob deferred, but empty), and confirms the extended-attribute + /// boundary is , thus avoiding a wasted round-trip. /// [Fact] public void LoadTopicGraph_WithExtendedDeferredAndNoBlob_ReturnsLoaded() { @@ -525,9 +520,9 @@ public void LoadTopicGraph_WithExtendedDeferredAndNoBlob_ReturnsLoaded() { | TEST: LOAD TOPIC GRAPH: WITH EXTENDED INCLUDED AND BLOB: RETURNS LOADED \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Calls with a row where HasExtendedAttributes is (extended included in result set), - /// and confirms the extended-attribute boundary is . + /// Calls with a row where + /// HasExtendedAttributes is (extended included in result set), and confirms the + /// extended-attribute boundary is . /// [Fact] public void LoadTopicGraph_WithExtendedIncludedAndBlob_ReturnsLoaded() { From 5b4bf6ba3d79f01f3aa1e83a99e2778b3854365c Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sat, 4 Jul 2026 01:20:40 -0700 Subject: [PATCH 041/337] Mark `Children.LoadState` in `LoadTopicGraph()` Utilizing the new `seedTopicId` (5f92c5f6), this update extends, this update a) constructs a list of all preexisting topics from the `referenceTopic` (`preExistingIds`); creates a map of all returned `hasChildren` without any of the `preExistingIds`; then crawls the line between the `seedTopicId` and of its ancestors that isn't in the `hasChildrenMap`. Why? Because for all of the topics we've loaded fresh, that weren't already in the topic graph, we can determine their `Children.LoadState` based on `HasChildren` and whether or not they have any children loaded. But for `@LoadAncestors`, that breaks because they'll have (exactly) one child, but could have more. And with topics previously loaded into memory, even if they were returned from `GetTopics`, we don't have sufficient information to determine their load state. (The one caveat to this is if we had a sparse tree and then did a comprehensive load over it; this would not properly mark those as Loaded. This seems like an unlikely edge case, but I may need to go back and revisit it.) This contributes to #111. --- OnTopic.Data.Sql/SqlDataReaderExtensions.cs | 38 +++++++++++++++++++-- 1 file changed, 35 insertions(+), 3 deletions(-) diff --git a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs index e6fd1fd5..0bf16824 100644 --- a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs +++ b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs @@ -5,7 +5,6 @@ \=============================================================================================================================*/ using System.Diagnostics; using System.Net; -using OnTopic.Attributes; using OnTopic.Collections.Specialized; using OnTopic.Querying; @@ -71,6 +70,8 @@ internal static class SqlDataReaderExtensions { var sqlDataReader = reader as SqlDataReader; var topics = referenceTopic is not null? referenceTopic.GetRootTopic().GetTopicIndex() : new(); var rootTopic = (Topic?)null; + var preExistingIds = new HashSet(topics.Keys); + var hasChildrenMap = new Dictionary(); /*-------------------------------------------------------------------------------------------------------------------------- | Populate topics @@ -79,7 +80,7 @@ internal static class SqlDataReaderExtensions { while (reader.Read()) { // Add the topic to the topic graph - var addedTopic = reader.AddTopic(topics, markDirty); + var addedTopic = reader.AddTopic(topics, markDirty); // The first topic returned is the root topic; store it for the return value rootTopic ??= addedTopic; @@ -90,6 +91,37 @@ internal static class SqlDataReaderExtensions { addedTopic.Attributes.LoadState = LoadState.NotLoaded; } + // HasChildren is NULL when the column is not applicable (e.g., in version or update paths); skip those topics. + // Pre-existing topics are excluded; their LoadState is already established, and they may have the lazy resolver wired up. + if (!preExistingIds.Contains(addedTopic.Id) && reader.GetNullableBoolean("HasChildren") is { } hasChildren) { + hasChildrenMap[addedTopic.Id] = hasChildren; + } + + } + + /*-------------------------------------------------------------------------------------------------------------------------- + | Stamp Children.LoadState + \-------------------------------------------------------------------------------------------------------------------------*/ + // Identifies the ancestor tree, stopping at the first pre-existing (i.e., not newly loaded) topic. Newly introduced + // ancestors have exactly one child loaded (from the ancestor crawl), but may have more; as such, they will be marked as + // NotLoaded. Note: An ancestor whose sole database child is part of the ancestor chain is still marked NotLoaded, since we + // don't have enough information to verify that. This is an unlikely scenario, but will cost one extra round-trip to verify. + var ancestorIds = new HashSet(); + if (topics.TryGetValue(seedTopicId, out var seedTopic)) { + var ancestor = seedTopic.Parent; + while (ancestor is not null && hasChildrenMap.ContainsKey(ancestor.Id)) { + ancestorIds.Add(ancestor.Id); + ancestor = ancestor.Parent; + } + } + + // HasChildren NULL (i.e., absent from the map) means the topic was not newly loaded or the column is not applicable; + // either way, skip. Ancestors with children are NotLoaded (partial load); other topics check whether any children were + // loaded, implying that @HasChildren or @LoadDescendants was passed, and thus its children are fully loaded. + foreach (var (id, hasChildren) in hasChildrenMap) { + var topic = topics[id]; + var isNotLoaded = hasChildren && (ancestorIds.Contains(id) || topic.Children.Count == 0); + topic.Children.LoadState = isNotLoaded? LoadState.NotLoaded : LoadState.Loaded; } /*-------------------------------------------------------------------------------------------------------------------------- @@ -109,7 +141,7 @@ internal static class SqlDataReaderExtensions { \-------------------------------------------------------------------------------------------------------------------------*/ Debug.WriteLine("SqlTopicRepository.Load(): SetExtendedAttributes() [" + DateTime.Now + "]"); - // Move to extened attributes dataset + // Move to extended attributes dataset reader.NextResult(); // Loop through each extended attribute record associated with a specific topic From 0cc3fc03a0aa805ab0bda11477a09c3b8df70a0e Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sat, 4 Jul 2026 01:25:51 -0700 Subject: [PATCH 042/337] Import namespaces to reduce code length Within the XML Docs, in particular, long reference signatures were made even longer because of namespaces. This was due to `OnTopic.Data.Sql.Models` not being imported because it created an ambiguous reference between `TopicReferencesDataTable` in `OnTopic.Data.Sql.Models` and `OnTopic.Tests.Schemas`. Whoops. To fix that, I added an alias to `TopicReferencesDataTable` to presume the test version, while I maintained the fully qualified name for the few references to the one in `OnTopic.Data.Sql.Models`. --- OnTopic.Tests/SqlTopicRepositoryTest.cs | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/OnTopic.Tests/SqlTopicRepositoryTest.cs b/OnTopic.Tests/SqlTopicRepositoryTest.cs index 17b10c99..ab6677d8 100644 --- a/OnTopic.Tests/SqlTopicRepositoryTest.cs +++ b/OnTopic.Tests/SqlTopicRepositoryTest.cs @@ -8,8 +8,10 @@ using Microsoft.Data.SqlClient; using OnTopic.Associations; using OnTopic.Data.Sql; +using OnTopic.Data.Sql.Models; using OnTopic.Tests.Schemas; using Xunit; +using TopicReferencesDataTable = OnTopic.Tests.Schemas.TopicReferencesDataTable; namespace OnTopic.Tests; @@ -544,13 +546,13 @@ public void LoadTopicGraph_WithExtendedIncludedAndBlob_ReturnsLoaded() { | TEST: TOPIC LIST DATA TABLE: ADD ROW: SUCCEEDS \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Constructs a and calls . Confirms that a with the expected data is returned. + /// Constructs a and calls . Confirms that a + /// with the expected data is returned. /// [Fact] public void TopicListDataTable_AddRow_Succeeds() { - var dataTable = new Data.Sql.Models.TopicListDataTable(); + var dataTable = new TopicListDataTable(); dataTable.AddRow(1); dataTable.AddRow(2); @@ -567,14 +569,13 @@ public void TopicListDataTable_AddRow_Succeeds() { | TEST: ATTRIBUTE VALUES DATA TABLE: ADD ROW: SUCCEEDS \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Constructs a and calls . Confirms that a with the expected data is - /// returned. + /// Constructs a , calls . Confirms that a with the expected data is returned. /// [Fact] public void AttributeValuesDataTable_AddRow_Succeeds() { - var dataTable = new Data.Sql.Models.AttributeValuesDataTable(); + var dataTable = new AttributeValuesDataTable(); dataTable.AddRow("Key", "Test"); dataTable.AddRow("ContentType", "Page"); @@ -591,9 +592,9 @@ public void AttributeValuesDataTable_AddRow_Succeeds() { | TEST: TOPIC REFERENCES DATA TABLE: ADD ROW: SUCCEEDS \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Constructs a and calls . Confirms that a with the expected data is - /// returned. + /// Constructs a and calls . Confirms that a with the + /// expected data is returned. /// [Fact] public void TopicReferencesDataTable_AddRow_Succeeds() { From e9bcbc83107f815172c8b6596d853bd36602f94f Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sat, 4 Jul 2026 01:27:45 -0700 Subject: [PATCH 043/337] Fixed wrapped `` formatting in XML Docs At least in JetBrains Rider, it accepts a wrapped `` so long as the entire quoted reference is on a single line. In a lot of these, the quote started on the first line, while the reference continued on the second line, causing a problem. --- OnTopic.Tests/SqlTopicRepositoryTest.cs | 36 ++++++++++++------------- 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/OnTopic.Tests/SqlTopicRepositoryTest.cs b/OnTopic.Tests/SqlTopicRepositoryTest.cs index ab6677d8..acf8edb1 100644 --- a/OnTopic.Tests/SqlTopicRepositoryTest.cs +++ b/OnTopic.Tests/SqlTopicRepositoryTest.cs @@ -616,8 +616,8 @@ public void TopicReferencesDataTable_AddRow_Succeeds() { | TEST: SQL COMMAND: ADD PARAMETER: STRING \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Creates a object and adds a parameter to it using the extension method. + /// Creates a object and adds a parameter to it using the extension method. /// [Fact] public void SqlCommand_AddParameter_String() { @@ -641,8 +641,8 @@ public void SqlCommand_AddParameter_String() { | TEST: SQL COMMAND: ADD PARAMETER: NULL STRING \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Creates a object and adds a null parameter value to it using the extension method. + /// Creates a object and adds a null parameter value to it using the extension method. /// [Fact] public void SqlCommand_AddParameter_NullString() { @@ -666,8 +666,8 @@ public void SqlCommand_AddParameter_NullString() { | TEST: SQL COMMAND: ADD PARAMETER: INT \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Creates a object and adds a parameter to it using the extension method. + /// Creates a object and adds a parameter to it using the extension method. /// [Fact] public void SqlCommand_AddParameter_Int() { @@ -691,8 +691,8 @@ public void SqlCommand_AddParameter_Int() { | TEST: SQL COMMAND: ADD PARAMETER: BOOL \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Creates a object and adds a parameter to it using the extension method. + /// Creates a object and adds a parameter to it using the extension method. /// [Fact] public void SqlCommand_AddParameter_Bool() { @@ -716,8 +716,8 @@ public void SqlCommand_AddParameter_Bool() { | TEST: SQL COMMAND: ADD PARAMETER: DATE/TIME \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Creates a object and adds a parameter to it using the extension method. + /// Creates a object and adds a parameter to it using the extension method. /// [Fact] public void SqlCommand_AddParameter_DateTime() { @@ -742,8 +742,8 @@ public void SqlCommand_AddParameter_DateTime() { | TEST: SQL COMMAND: ADD PARAMETER: DATA TABLE \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Creates a object and adds a parameter to it using the extension method. + /// Creates a object and adds a parameter to it using the extension method. /// [Fact] public void SqlCommand_AddParameter_DataTable() { @@ -769,8 +769,8 @@ public void SqlCommand_AddParameter_DataTable() { | TEST: SQL COMMAND: ADD PARAMETER: STRING BUILDER \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Creates a object and adds a parameter to it using the extension method. + /// Creates a object and adds a parameter to it using the extension method. /// [Fact] public void SqlCommand_AddParameter_StringBuilder() { @@ -795,8 +795,8 @@ public void SqlCommand_AddParameter_StringBuilder() { | TEST: SQL COMMAND: ADD OUTPUT PARAMETER: RETURN CODE \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Creates a object and adds a parameter to it using the extension method. + /// Creates a object and adds a parameter to it using the extension method. /// [Fact] public void SqlCommand_AddOutputParameter_ReturnCode() { @@ -823,8 +823,8 @@ public void SqlCommand_AddOutputParameter_ReturnCode() { | TEST: SQL COMMAND: ADD OUTPUT PARAMETER: RETURN DEFAULT \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Creates a object and adds a parameter to it using the extension method. Ensures the default return code is + /// Creates a object and adds a parameter to it using the extension method. Ensures the default return code is /// returned, if the value isn't explicitly set. /// [Fact] From 7da41f5567c412dfc560780f847ea8894c74029c Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sat, 4 Jul 2026 01:34:44 -0700 Subject: [PATCH 044/337] Introduced basic unit tests for `HasChildren` This test evaluates that `HasChildren` bit (e3e7cfba) in the `TopicsDataTable` (78602c2b) corresponds appropriately with the `Children.LoadState` (486f963c, 94c86661). This helps affirm the state of the lazy-loading implementation (#111). --- OnTopic.Tests/SqlTopicRepositoryTest.cs | 77 +++++++++++++++++++++++++ 1 file changed, 77 insertions(+) diff --git a/OnTopic.Tests/SqlTopicRepositoryTest.cs b/OnTopic.Tests/SqlTopicRepositoryTest.cs index acf8edb1..d3c0a236 100644 --- a/OnTopic.Tests/SqlTopicRepositoryTest.cs +++ b/OnTopic.Tests/SqlTopicRepositoryTest.cs @@ -542,6 +542,83 @@ public void LoadTopicGraph_WithExtendedIncludedAndBlob_ReturnsLoaded() { } + /*============================================================================================================================ + | TEST: LOAD TOPIC GRAPH: WITH HAS CHILDREN FALSE: RETURNS CHILDREN LOADED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Calls with a row where HasChildren + /// is and confirms that is (the + /// topic is a leaf with nothing to lazy-load). + /// + [Fact] + public void LoadTopicGraph_WithHasChildrenFalse_ReturnsChildrenLoaded() { + + using var topics = new TopicsDataTable(); + + topics.AddRow(1, "Root", "Container", null, hasChildren: false); + + using var tableReader = new DataTableReader(topics); + + var topic = tableReader.LoadTopicGraph(1); + + Assert.Equal(LoadState.Loaded, topic?.Children.LoadState); + + } + + /*============================================================================================================================ + | TEST: LOAD TOPIC GRAPH: WITH HAS CHILDREN AND LOADED CHILDREN: RETURNS CHILDREN LOADED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Calls with a parent row where HasChildren is and the child rows are present in the result set, confirming that is (i.e., the subtree was loaded in full). + /// + [Fact] + public void LoadTopicGraph_WithHasChildrenAndLoadedChildren_ReturnsChildrenLoaded() { + + using var topics = new TopicsDataTable(); + + topics.AddRow(1, "Root", "Container", null, hasChildren: true); + topics.AddRow(2, "Child", "Page", 1, hasChildren: false); + + using var tableReader = new DataTableReader(topics); + + var topic = tableReader.LoadTopicGraph(1); + + Assert.Equal(LoadState.Loaded, topic?.Children.LoadState); + + } + + /*============================================================================================================================ + | TEST: LOAD TOPIC GRAPH: WITH HAS CHILDREN ON ANCESTOR AND LOADED SUBTREE: SETS LOAD STATE CORRECTLY + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Calls with a result set that includes both ancestor and a fully + /// loaded subtree, confirming that ancestor topics are stamped (i.e., partial children) + /// while subtree topics are stamped (i.e., all children present). This is the primary + /// scenario addressed by the seedTopicId parameter; i.e., loading ascendants and descendants. + /// + [Fact] + public void LoadTopicGraph_WithHasChildrenOnAncestorAndLoadedSubtree_SetsLoadStateCorrectly() { + + using var topics = new TopicsDataTable(); + + topics.AddRow(1, "Root", "Container", null, hasChildren: true); + topics.AddRow(2, "Child", "Container", 1, hasChildren: true); + topics.AddRow(3, "Grandchild", "Page", 2, hasChildren: false); + + using var tableReader = new DataTableReader(topics); + + // The seed topic is Child (2); Root (1) is on the ancestor chain and is NotLoaded. + // The Child (seed) and Grandchild are in the fully loaded subtree and are Loaded. + var rootTopic = tableReader.LoadTopicGraph(2); + var childTopic = rootTopic?.Children.FirstOrDefault(); + + Assert.Equal(LoadState.NotLoaded, rootTopic?.Children.LoadState); + Assert.Equal(LoadState.Loaded, childTopic?.Children.LoadState); + + } + /*============================================================================================================================ | TEST: TOPIC LIST DATA TABLE: ADD ROW: SUCCEEDS \---------------------------------------------------------------------------------------------------------------------------*/ From 22161b12c4f3b0ce5882c171c07663283dd8ba91 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sat, 4 Jul 2026 14:23:10 -0700 Subject: [PATCH 045/337] Establish local cache for `CachedTopicRepository` Instead of doing a crawl of the entire topic graph for every load request using the `TopicExtensions`, instead create a fill a local cache by both Topic ID and Unique Key. This will not be sufficient on its own, as the cache will need to be updated as new topics are loading (via `Load()` or via `EnsureLoaded()`), saved (`Save()`, moved (`Move()`), renamed (`Rename()`), or deleted (`Delete()`). The last four will be handled via either overriding those methods or by subscribing to the events handled by the `ObservableTopicRepository`. This not only provides a significant performance boost to `CachedTopicRepository`, but additionally helps support #111. --- OnTopic.Data.Caching/CachedTopicRepository.cs | 22 ++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/OnTopic.Data.Caching/CachedTopicRepository.cs b/OnTopic.Data.Caching/CachedTopicRepository.cs index 54d7a8ba..b48e0e2e 100644 --- a/OnTopic.Data.Caching/CachedTopicRepository.cs +++ b/OnTopic.Data.Caching/CachedTopicRepository.cs @@ -26,6 +26,8 @@ public class CachedTopicRepository : TopicRepositoryDecorator, ITopicLoadResolve | VARIABLES \---------------------------------------------------------------------------------------------------------------------------*/ private readonly Topic _cache; + private readonly Dictionary _topicById = new(); + private readonly Dictionary _topicByKey = new(StringComparer.OrdinalIgnoreCase); /*============================================================================================================================ | CONSTRUCTOR @@ -52,10 +54,18 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos ); /*-------------------------------------------------------------------------------------------------------------------------- - | Ensure topics are loaded + | Establish cache \-------------------------------------------------------------------------------------------------------------------------*/ _cache = rootTopic; + /*-------------------------------------------------------------------------------------------------------------------------- + | Populate flat index from loaded graph + \-------------------------------------------------------------------------------------------------------------------------*/ + foreach (var topic in _cache.FindAll()) { + _topicById[topic.Id] = topic; + _topicByKey[topic.GetUniqueKey()] = topic; + } + /*-------------------------------------------------------------------------------------------------------------------------- | Stamp resolver on loaded graph \-------------------------------------------------------------------------------------------------------------------------*/ @@ -82,9 +92,10 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos } /*-------------------------------------------------------------------------------------------------------------------------- - | Recursive search + | Lookup by topic identifier \-------------------------------------------------------------------------------------------------------------------------*/ - return _cache.FindFirst(t => t.Id.Equals(topicId)); + _topicById.TryGetValue(topicId, out var topic); + return topic; } @@ -104,9 +115,10 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos } /*-------------------------------------------------------------------------------------------------------------------------- - | Lookup by TopicKey + | Lookup by unique key \-------------------------------------------------------------------------------------------------------------------------*/ - return _cache.GetByUniqueKey(uniqueKey); + _topicByKey.TryGetValue(uniqueKey, out var topic); + return topic; } From d5084085e7d30300a7e399d9b1c78f124bcf910d Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sat, 4 Jul 2026 14:52:22 -0700 Subject: [PATCH 046/337] Introduced event handlers for maintaining indexes Override the `OnTopicSaved()`, `OnTopicDeleted()`, `OnTopicMoved()`, and `OnTopicRenamed()` event handlers from `ObservableTopicRepository` in order to ensure the newly established indexes on the `CachedTopicRepository` are maintained (22161b12). This includes a shared `RekeyTopicSubtree()` helper function to handle the shared logic between `OnTopicMoved()` and `OnTopicRenamed()`. This contributes to #111. --- OnTopic.Data.Caching/CachedTopicRepository.cs | 112 ++++++++++++++++++ 1 file changed, 112 insertions(+) diff --git a/OnTopic.Data.Caching/CachedTopicRepository.cs b/OnTopic.Data.Caching/CachedTopicRepository.cs index b48e0e2e..dc1945b7 100644 --- a/OnTopic.Data.Caching/CachedTopicRepository.cs +++ b/OnTopic.Data.Caching/CachedTopicRepository.cs @@ -212,4 +212,116 @@ public virtual Task EnsureLoadedAsync(Topic topic, TopicPayload boundaries, Canc } + /*============================================================================================================================ + | METHODS: EVENT HANDLERS + \---------------------------------------------------------------------------------------------------------------------------*/ + + /// + /// + /// Adds newly-created topics to the flat index. When the save is recursive, all resident descendants are indexed as well, + /// since only one event fires for the root of a recursive save. + /// + protected override void OnTopicSaved(TopicSaveEventArgs args) { + + // Setup + Contract.Requires(args); + base.OnTopicSaved(args); + + // Index newly created topics and, when saved recursively, any new descendants + if (args.IsNew) { + foreach (var topic in args.Topic.FindAll()) { + _topicById[topic.Id] = topic; + _topicByKey[topic.GetUniqueKey()] = topic; + } + } + + } + + /// + /// + /// Removes the deleted topic and all of its descendants from the flat index. Called after the topic has been detached from + /// its parent's collection but before the topic graph is torn down, so on the deleted topic still returns the full subtree. + /// + protected override void OnTopicDeleted(TopicEventArgs args) { + + // Setup + Contract.Requires(args); + base.OnTopicDeleted(args); + + // Remove the deleted subtree from both indices + foreach (var topic in args.Topic.FindAll()) { + _topicById.Remove(topic.Id); + _topicByKey.Remove(topic.GetUniqueKey()); + } + + } + + /// + /// + /// Rebuilds the unique-key index entries for the moved topic and all of its descendants. The move has already completed by + /// the time this fires, so the old root key is reconstructed from and the topic's + /// (unchanged) . + /// + protected override void OnTopicMoved(TopicMoveEventArgs args) { + + // Setup + Contract.Requires(args); + base.OnTopicMoved(args); + + // Reconstruct the old root unique key from the source parent and the (unchanged) topic key + var oldRootUniqueKey = args.Source is null + ? args.Topic.Key + : $"{args.Source.GetUniqueKey()}:{args.Topic.Key}"; + + // Reindex topic and children + RekeyTopicSubtree(args.Topic, oldRootUniqueKey); + + } + + /// + /// + /// Rebuilds the unique-key index entries for the renamed topic and all of its descendants. The rename has already been + /// applied to by the time this fires, so the old root key is reconstructed from the (unchanged) + /// parent path and . + /// + protected override void OnTopicRenamed(TopicRenameEventArgs args) { + + // Setup + Contract.Requires(args); + base.OnTopicRenamed(args); + + // Reconstruct the old root unique key from the (unchanged) parent path and the original key + var oldRootUniqueKey = args.Topic.Parent is null + ? args.OriginalKey + : $"{args.Topic.Parent.GetUniqueKey()}:{args.OriginalKey}"; + + // Reindex topic and children + RekeyTopicSubtree(args.Topic, oldRootUniqueKey); + + } + + /*============================================================================================================================ + | METHODS: PRIVATE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Removes stale entries for and its descendants by swapping the + /// prefix for the current one, then re-indexes the subtree under its current unique + /// keys. + /// + private void RekeyTopicSubtree(Topic topic, string oldRootUniqueKey) { + + // Establish variables + var newRootUniqueKey = topic.GetUniqueKey(); + + // Remove each stale unique-key entry and replace it with the current unique key + foreach (var subtopic in topic.FindAll()) { + var currentKey = subtopic.GetUniqueKey(); + var oldKey = oldRootUniqueKey + currentKey[newRootUniqueKey.Length..]; + _topicByKey.Remove(oldKey); + _topicByKey[currentKey] = subtopic; + } + + } + } //Class \ No newline at end of file From 39bf06df1e89b973ba60ce9fe1b8ba803a5e1d23 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sat, 4 Jul 2026 15:06:57 -0700 Subject: [PATCH 047/337] Established backing field for `Topic.Children` In the future, as part of #111, calling `Topic.Children` on a collection that is set to a `LoadState.NotLoaded` will trigger the `ITopicLoadResolver` to call `EnsureLoaded()`, resulting in a call to the persistence store. Internal calls from topic generally should not do this. To get around this, I've established a backing field for `Children` called `_children` that access can go through. Critically, while this is a private field, `Topic` is able to access this on another `Topic`, including its parent, and so this can be used for e.g., `SetParent()` to add a new topic to a parent's children collection even if that collection is not yet (fully) loaded. This is a key foundation for lazy-loading (#111) children. --- OnTopic/Topic.cs | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/OnTopic/Topic.cs b/OnTopic/Topic.cs index ca3cfeb9..293d64b6 100644 --- a/OnTopic/Topic.cs +++ b/OnTopic/Topic.cs @@ -30,6 +30,7 @@ public class Topic: ITrackDirtyKeys { private string _contentType; private string? _originalKey; private Topic? _parent; + private readonly KeyedTopicCollection _children = new(); readonly DirtyKeyCollection _dirtyKeys = new(); internal ITopicLoadResolver? _resolver; @@ -60,7 +61,6 @@ public Topic(string key, string contentType, Topic? parent = null, int id = -1) /*-------------------------------------------------------------------------------------------------------------------------- | Set collections \-------------------------------------------------------------------------------------------------------------------------*/ - Children = new(); Attributes = new(this); IncomingRelationships = new(this, true); Relationships = new(this, false); @@ -147,7 +147,7 @@ public Topic? Parent { set { if (_parent != value) { Contract.Requires(value, "Parent cannot be explicitly set to null."); - SetParent(value, value.Children.LastOrDefault()); + SetParent(value, value._children.LastOrDefault()); } } } @@ -161,7 +161,7 @@ public Topic? Parent { /// /// The children of the current . /// - public KeyedTopicCollection Children { get; } + public KeyedTopicCollection Children => _children; /*============================================================================================================================ | METHOD: IS LOADED @@ -178,7 +178,7 @@ public Topic? Parent { public bool IsLoaded(TopicPayload boundaries) { // Children - if (boundaries.HasFlag(TopicPayload.Children) && Children.LoadState is not LoadState.Loaded) { + if (boundaries.HasFlag(TopicPayload.Children) && _children.LoadState is not LoadState.Loaded) { return false; } @@ -370,7 +370,7 @@ public string Key { _originalKey ??= _key; //If an established key value is changed, the parent's index must be manually updated; this won't happen automatically. if (_originalKey is not null && !value.Equals(_key, StringComparison.OrdinalIgnoreCase) && Parent is not null) { - Parent.Children.ChangeKey(this, value); + Parent._children.ChangeKey(this, value); } _key = value; } @@ -618,7 +618,7 @@ public void SetParent(Topic parent, Topic? sibling = null) { /*-------------------------------------------------------------------------------------------------------------------------- | Check to ensure that the topic isn't being moved to a parent with a duplicate key \-------------------------------------------------------------------------------------------------------------------------*/ - if (parent != _parent && parent.Children.Contains(Key)) { + if (parent != _parent && parent._children.Contains(Key)) { throw new InvalidKeyException( $"Duplicate key when setting Parent property: the topic with the name '{Key}' already exists in the '{parent.Key}' " + $"topic." @@ -628,9 +628,9 @@ public void SetParent(Topic parent, Topic? sibling = null) { /*-------------------------------------------------------------------------------------------------------------------------- | Move topic to new location \-------------------------------------------------------------------------------------------------------------------------*/ - _parent?.Children.Remove(Key); - var insertAt = (sibling is not null)? parent.Children.IndexOf(sibling)+1 : 0; - parent.Children.Insert(insertAt, this); + _parent?._children.Remove(Key); + var insertAt = (sibling is not null)? parent._children.IndexOf(sibling)+1 : 0; + parent._children.Insert(insertAt, this); _dirtyKeys.MarkDirty("Parent"); /*-------------------------------------------------------------------------------------------------------------------------- From 110584bac0e0d6e8661f85dbeac83be8ee77c6e4 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sat, 4 Jul 2026 15:28:06 -0700 Subject: [PATCH 048/337] Gate recursive save by `LoadState` When recursively saving children via `Save(topic, isRecursive)`, check to confirm the child topic is loaded before recursing further. Otherwise, this will trigger a lazy-loading of children. Note that it is conceivable, though unlikely, that a `IsNew` or `IsDirty` child lives under a `Children` collection that has a `LoadState` of `NotLoaded`. This wouldn't occur in our normal workflows, such as the OnTopic Editor, or even our custom client forms, but is rather a possibility when programmatically modifying trees. That said, programmatically modifying a tree that isn't fully loaded exposes a number of risks, which developers performing such tasks are expected to be familiar with. These edge risks are worth the performance benefits for the vast majority of read-only states. This contributes to #111. --- OnTopic/Repositories/TopicRepository.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/OnTopic/Repositories/TopicRepository.cs b/OnTopic/Repositories/TopicRepository.cs index 93c8261b..475217a6 100644 --- a/OnTopic/Repositories/TopicRepository.cs +++ b/OnTopic/Repositories/TopicRepository.cs @@ -452,7 +452,7 @@ _contentTypeDescriptors is not null && /*-------------------------------------------------------------------------------------------------------------------------- | Recurse over children \-------------------------------------------------------------------------------------------------------------------------*/ - if (isRecursive) { + if (isRecursive && topic.IsLoaded(TopicPayload.Children)) { foreach (var childTopic in topic.Children.ToList()) { Save(childTopic, isRecursive, unresolvedTopics, version); } From cac32ba9af6f3e380f4ce014fe460a875bf0f7f7 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sat, 4 Jul 2026 15:37:24 -0700 Subject: [PATCH 049/337] Reformatting `Load()` signatures When i added the `TopicPayload` to the `Load()` overloads (58524089), I wrapped most of the signatures onto multiple lines since they'd gotten quite long, and had exceeded our 128 character code length. Unfortunately, I missed this one, in the core implementation itself. While I was at it, I improved the documentation for `isRecursive` to clarify the behavior. --- OnTopic/Repositories/ITopicRepository.cs | 23 +++++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/OnTopic/Repositories/ITopicRepository.cs b/OnTopic/Repositories/ITopicRepository.cs index 95d25dc0..bc47c623 100644 --- a/OnTopic/Repositories/ITopicRepository.cs +++ b/OnTopic/Repositories/ITopicRepository.cs @@ -97,10 +97,18 @@ public interface ITopicRepository { /// When loading a single topic or branch, offers a reference topic graph that can be used to ensure that topic /// associations—such as references, relationships, and —are integrated with existing entities. /// - /// Determines whether or not to recurse through and load a topic's children. + /// + /// Whether to load the full descendant subtree rooted at the seed topic. When , only the seed topic + /// itself is loaded. Ancestor topics are always loaded when needed to place the seed topic within the graph. + /// /// Specifies which data to include with each topic. /// A topic object. - Topic? Load(int topicId, Topic? referenceTopic = null, bool isRecursive = true, TopicPayload payload = TopicPayload.All); + Topic? Load( + int topicId, + Topic? referenceTopic = null, + bool isRecursive = true, + TopicPayload payload = TopicPayload.All + ); /// /// Loads a (and, optionally, all of its descendants) based on the specified —are integrated with existing entities. /// - /// Determines whether or not to recurse through and load a topic's children. + /// + /// Whether to load the full descendant subtree. See for details. + /// /// /// Specifies which data to include with each topic. See /// for details. /// /// A topic object. - Topic? Load(string uniqueKey, Topic? referenceTopic = null, bool isRecursive = true, TopicPayload payload = TopicPayload.All); + Topic? Load( + string uniqueKey, + Topic? referenceTopic = null, + bool isRecursive = true, + TopicPayload payload = TopicPayload.All + ); /// [ExcludeFromCodeCoverage] From 4d83e0e1846ee75b7ca04b59ff882450e5100eea Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sat, 4 Jul 2026 16:13:28 -0700 Subject: [PATCH 050/337] Gated `FindFirst()`, FindAll()` on `LoadState` MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Lazy-loading introduces some critical limitations for the `TopicExtensions`, which allow the in-memory tree to be crawled recursively to find topics that meet certain criteria. That only works, though, assuming the relevant topics are loaded into memory. These methods do not fall back to database lookups. That was fine when we presumed the entire topic graph would be available in memory. It limits the usefulness of these features in the case of a sparse or partial topic in-memory graph. This is even more limited in that calls to `Children` that aren't loaded will trigger a database load, which could make an innocent seeming call to `FindFirst()` or `FindAll()` to become very expensive, triggering hundreds, maybe thousands of synchronous calls to fill the data. To avoid this, crawling children is gated based on `IsLoaded()`/`LoadState`. That said, even with this, there remain potential issues, as the `predicate` passed to `FindFirst()` or `FindAll()` could easily trigger any of the lazy loading on the topics they're checking. Developer beware! Given then, I'm tempted to make this an internal-only library. It remains useful, and is used extensively internally, but is also a risky library to use in conjunction with lazy-loading unless the developer takes care, and understands the trigger points. In the meanwhile, I've spammed the XML Docs with warnings regarding this. That said, I didn't gate `GetByUniqueKey()` since that's a deterministic path, with a limited cost, and would introduce quite a few potential issues if it wasn't supported. We may revisit how that's handled later, but for now this ensures backward compatibility, even if at a cost. This contributes to—or, rather, is in response to—#111. --- OnTopic/Querying/TopicExtensions.cs | 63 ++++++++++++++++++++++++----- 1 file changed, 52 insertions(+), 11 deletions(-) diff --git a/OnTopic/Querying/TopicExtensions.cs b/OnTopic/Querying/TopicExtensions.cs index 9acece90..088e37bd 100644 --- a/OnTopic/Querying/TopicExtensions.cs +++ b/OnTopic/Querying/TopicExtensions.cs @@ -6,6 +6,7 @@ using OnTopic.Collections; using OnTopic.Collections.Specialized; using OnTopic.Metadata; +using OnTopic.Repositories; namespace OnTopic.Querying; @@ -15,6 +16,12 @@ namespace OnTopic.Querying; /// /// Provides extensions for querying . /// +/// +/// These extensions, while powerful, were intended to be used against fully loaded, in-memory topic trees. Their usefulness +/// with lazy-loaded trees is limited and, potentially, even expensive, as innocent seeming queries may trigger lazy-loading +/// of attributes, relationships, references, children, &c. Children are gated in and , but the predicate parameter can easily call into any of these. +/// public static class TopicExtensions { /*============================================================================================================================ @@ -23,6 +30,11 @@ public static class TopicExtensions { /// /// Finds the first instance of a in the topic tree that satisfies the delegate. /// + /// + /// When using this with a lazy-loaded tree, be aware that it may trigger costly on-demand loading of attributes, + /// relationships, references, and children if they're included in the . It is recommended to + /// avoid use with lazy-loaded trees, or to use extreme caution. + /// /// The instance of the to operate against; populated automatically by .NET. /// The function to validate whether a should be included in the output. /// The first instance of the topic to be satisfied. @@ -44,10 +56,12 @@ public static class TopicExtensions { /*-------------------------------------------------------------------------------------------------------------------------- | Recurse over children \-------------------------------------------------------------------------------------------------------------------------*/ - foreach (var child in topic.Children) { - var nestedResult = child.FindFirst(predicate); - if (nestedResult is not null) { - return nestedResult; + if (topic.IsLoaded(TopicPayload.Children)) { + foreach (var child in topic.Children) { + var nestedResult = child.FindFirst(predicate); + if (nestedResult is not null) { + return nestedResult; + } } } @@ -103,7 +117,8 @@ public static class TopicExtensions { | METHOD: FIND ALL \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Retrieves a collection of all topics descending from—and including—the current topic. + /// Retrieves a collection of all in-memory topics in the tree, descending from—and including—the + /// current topic. /// /// The instance of the to operate against; populated automatically by .NET. /// A collection of topics descending from the current topic. @@ -112,6 +127,11 @@ public static class TopicExtensions { /// /// Retrieves a collection of topics based on a supplied function. /// + /// + /// When using this with a lazy-loaded tree, be aware that it may trigger costly on-demand loading of attributes, + /// relationships, references, and children if they're included in the . It is recommended to + /// avoid use with lazy-loaded trees, or to use extreme caution. + /// /// The instance of the to operate against; populated automatically by .NET. /// The function to validate whether a should be included in the output. /// A collection of topics matching the input parameters. @@ -135,11 +155,13 @@ public static ReadOnlyTopicCollection FindAll(this Topic topic, Func /// Retrieves a collection of topics based on an attribute name and value. /// + /// + /// If querying a lazy-loaded topic tree, this will trigger a query for any extended attributes that aren't yet (fully) + /// loaded. At the same time, however, it will not trigger lazy-loading of any children that aren't yet (fully) loaded. As a + /// result, queries against lazy-loaded topic trees can be slow while also being incomplete. + /// /// The instance of the to operate against; populated automatically by .NET. /// The string identifier for the against which to be searched. /// The text value for the against which to be searched. @@ -193,8 +220,12 @@ public static ReadOnlyTopicCollection FindAllByAttribute(this Topic topic, strin | METHOD: GET TOPIC INDEX \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Retrieves all topics from the topic cache, and places them in an dictionary indexed by . + /// Retrieves all topics from the in-memory topic graph, and places them in a dictionary indexed by . /// + /// + /// This only loads topics from the in-memory topic graph. Any topics that aren't yet loaded in the in-memory topic graph + /// will not be included. + /// /// The instance of the to operate against; populated automatically by .NET. /// A dictionary of topics indexed by . public static TopicIndex GetTopicIndex(this Topic topic) => new(topic.FindAll()); @@ -215,6 +246,11 @@ public static ReadOnlyTopicCollection FindAllByAttribute(this Topic topic, strin /// /// Retrieves a with the specified , if available. /// + /// + /// This will trigger synchronous lazy-loading calls to any topics in the chain whose children aren't yet loaded. That can + /// make initial calls to this unexpectedly expensive on a lazy-loaded topic tree, resulting in multiple calls to the + /// underlying persistance store. + /// /// The instance of the to operate against; populated automatically by .NET. /// The of the to return. /// A with the specified , if found. @@ -266,6 +302,11 @@ public static ReadOnlyTopicCollection FindAllByAttribute(this Topic topic, strin /// /// Retrieves the for the current . /// + /// + /// This assumes that the Configuration tree is fully loaded as part of the 's graph. In a standard + /// configuration, this portion of the tree should be eagerly loaded as part of the cache initialization, since it's a + /// commonly referenced dependency with a lot of internal dependencies in terms of relationships and references. + /// /// The instance of the to operate against; populated automatically by .NET. /// The associated with the . public static ContentTypeDescriptor? GetContentTypeDescriptor(this Topic topic) { From 1968876525ee92d4429487646631f91657bd5436 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sat, 4 Jul 2026 16:22:12 -0700 Subject: [PATCH 051/337] Ensure ascendants loaded for potential orphans When loading a topic that isn't the root and doesn't have an existing, in-memory `referenceTopic` it's grounded to, ensure that we load ascendants so that the topic (of arbitrary depth) has context and, if needed, can be connected back to a topic tree. That said, the `referenceTopic` itself isn't as clear of a signal as I'd prefer, because it could just be a reference to any topic within an in-memory graph, and isn't necessarily the parent of the new topic, or even has the parent of the new topic in memory. That's a gap in tis implementation that will require additional care. --- OnTopic.Data.Sql/SqlTopicRepository.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index 5d4c8c8d..c3092025 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -143,7 +143,7 @@ public override Topic Load( \-------------------------------------------------------------------------------------------------------------------------*/ command.AddParameter("TopicID", topicId); command.AddParameter("LoadDescendants", isRecursive); - command.AddParameter("LoadAscendants", !isRecursive); + command.AddParameter("LoadAscendants", topicId >= 0 && referenceTopic is null); command.AddParameter("IncludeExtended", payload.HasFlag(TopicPayload.ExtendedAttributes)); /*-------------------------------------------------------------------------------------------------------------------------- From 74db74096be76e36f56b346d21cc23514a77fa64 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sat, 4 Jul 2026 16:27:07 -0700 Subject: [PATCH 052/337] Lazy-load `Children` via `EnsureLoaded()` While I previously wired up most of the lazy-loading options in `SqlTopicRepository`, I had held off on fully integrating children until further scaffolding was in place, such as establishing the `_children` backing field (39bf06df) to avoid triggering loads while checking e.g., `LoadState`. Now that those are in place, is the final piece necessary to implement before enabling that lazy-loading (#111). (This allows lazy-loading of children, but it's not wired up to any triggers yet.) --- OnTopic.Data.Sql/SqlTopicRepository.cs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index c3092025..7a710353 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -891,9 +891,10 @@ private static void AddEnsureLoadedParameters(SqlCommand command, int topicId, T // Set the topic we're working with command.AddParameter("TopicID", topicId); - // Scope: Always None (i.e., single node) for resolver fills + // Scope: LoadChildren when filling the Children, otherwise we're only interested in this topic's content command.AddParameter("LoadDescendants", false); command.AddParameter("LoadAscendants", false); + command.AddParameter("LoadChildren", boundaries.HasFlag(TopicPayload.Children)); // Payload: Include only what the requested boundaries require command.AddParameter("IncludeIndexed", boundaries.HasFlag(TopicPayload.Children)); From 3eae28311fccdb32dc55c684425ce9cee87dcdac Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sat, 4 Jul 2026 16:41:21 -0700 Subject: [PATCH 053/337] Provide test for gate on recursive `Save()` In a previous update, I prevented a recursive `TopicRepository.Save()` from triggering a lazy-load of children that aren't yet (fully) loaded (110584ba). This provides a unit test to confirm that is working as expected, and contributes to #111. --- OnTopic.Tests/TopicRepositoryBaseTest.cs | 31 ++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/OnTopic.Tests/TopicRepositoryBaseTest.cs b/OnTopic.Tests/TopicRepositoryBaseTest.cs index 0a3d05d5..f6f8a5a8 100644 --- a/OnTopic.Tests/TopicRepositoryBaseTest.cs +++ b/OnTopic.Tests/TopicRepositoryBaseTest.cs @@ -1154,6 +1154,28 @@ public void Save_NewTopic_StampsResolver() { } + /*============================================================================================================================ + | TEST: SAVE: NOT LOADED CHILDREN: SKIPS RECURSIVE DESCENT + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Creates a parent topic with a child, marks the parent's as , then saves recursively. Verifies that the child is not saved; the recursive-save loop is gated on , so a not-loaded children collection prevents descent. + /// + [Fact] + public void Save_NotLoadedChildren_SkipsRecursiveDescent() { + + var parent = new Topic("Parent", "Page"); + var child = new Topic("Child", "Page", parent); + + parent.Children.LoadState = LoadState.NotLoaded; + + _topicRepository.Save(parent, isRecursive: true); + + Assert.True(child.IsNew); + + } + /*============================================================================================================================ | TEST: ENSURE LOADED: EXTENDED ATTRIBUTES NOT LOADED: MARKS LOADED \---------------------------------------------------------------------------------------------------------------------------*/ @@ -1204,6 +1226,10 @@ public void EnsureLoaded_MixedBoundaries_SkipsLoadedBoundaries() { /// and confirms that promotes the boundary to via the 's fill. /// + /// + /// On-demand fetching of non-resident relationship targets is deferred to lazy-loading-plan.md Task 6. A stub fill + /// simply marks the boundary ; the SQL resolver leaves it + /// whenever any target is not resident in the single-node topic index it currently uses. /// [Fact] public void EnsureLoaded_RelationshipsNotLoaded_MarksLoaded() { @@ -1225,6 +1251,11 @@ public void EnsureLoaded_RelationshipsNotLoaded_MarksLoaded() { /// confirms that promotes the boundary to /// via the 's fill. /// + /// + /// On-demand fetching of non-resident reference targets is deferred to lazy-loading-plan.md Task 6. A stub fill + /// simply marks the boundary ; the SQL resolver leaves it + /// whenever any target is not resident in the single-node topic index it currently uses. + /// [Fact] public void EnsureLoaded_ReferencesNotLoaded_MarksLoaded() { From 7fa99cc86661c0566e7c6a9a0984fcaa00f066cf Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sat, 4 Jul 2026 16:44:43 -0700 Subject: [PATCH 054/337] Provide test for `FindFirst()`, `FindAll()` gates In a previous update, I gated `FindFirst()` and `FindAll()` based on the `LoadState` of `Children` via `IsLoaded()` to ensure they don't trigger lazy-loading of not yet (fully) loaded children (4d83e0e1). These test verifies that functionality, and contributes to #111. --- OnTopic.Tests/TopicQueryingTest.cs | 52 ++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/OnTopic.Tests/TopicQueryingTest.cs b/OnTopic.Tests/TopicQueryingTest.cs index bd139e30..145acead 100644 --- a/OnTopic.Tests/TopicQueryingTest.cs +++ b/OnTopic.Tests/TopicQueryingTest.cs @@ -351,4 +351,56 @@ public void AnyNew_ContainsExisting_ReturnFalse() { } + /*============================================================================================================================ + | TEST: FIND FIRST: NOT LOADED CHILD: DOES NOT DESCEND + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Creates a three-level topic hierarchy and manually sets the middle topic's to . Verifies that stops at that node and does not return + /// the grandchild, which would only be reachable by descending into the not-loaded subtree. + /// + [Fact] + public void FindFirst_WithNotLoadedChild_DoesNotDescend() { + + var parent = new Topic("Parent", "Page", null, 1); + var child = new Topic("Child", "Page", parent, 2); + var grandchild = new Topic("Grandchild", "Page", child, 3); + + child.Children.LoadState = LoadState.NotLoaded; + + var result = parent.FindFirst(t => t == grandchild); + + Assert.Null(result); + + } + + /*============================================================================================================================ + | TEST: FIND ALL: PARTIALLY LOADED GRAPH: EXCLUDES NOT LOADED SUBTREES + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Creates a topic graph where one branch has a children collection. Verifies that includes the not-loaded node itself (it is resident) but excludes its + /// descendants, which are unreachable without triggering a load. + /// + [Fact] + public void FindAll_WithPartiallyLoadedGraph_ExcludesNotLoadedSubtrees() { + + var parent = new Topic("Parent", "Page", null, 1); + var childA = new Topic("ChildA", "Page", parent, 2); + var childB = new Topic("ChildB", "Page", parent, 3); + var grandchildA = new Topic("GrandchildA", "Page", childA, 4); + var grandchildB = new Topic("GrandchildB", "Page", childB, 5); + + childB.Children.LoadState = LoadState.NotLoaded; + + var results = parent.FindAll(); + + Assert.Contains(parent, results); + Assert.Contains(childA, results); + Assert.Contains(grandchildA, results); + Assert.Contains(childB, results); + Assert.DoesNotContain(grandchildB, results); + + } + } //Class \ No newline at end of file From c14bff724131b81f043d74c52e09b0a5208e5d80 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sat, 4 Jul 2026 17:04:45 -0700 Subject: [PATCH 055/337] Ensure the topic requested is loaded In a previous update, I conditionally exposed the `@LoadAscendants` parameter of the `GetTopics` stored procedure (19688765). But that means if you request `Load(topicId)` you may not get the topic you requested, but the root node, with a chain all the way down to the topic requested. Instead, ensure that the "seed" topic is returned. --- OnTopic.Data.Sql/SqlDataReaderExtensions.cs | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs index 0bf16824..3ab08982 100644 --- a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs +++ b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs @@ -193,7 +193,9 @@ internal static class SqlDataReaderExtensions { /*-------------------------------------------------------------------------------------------------------------------------- | Return objects \-------------------------------------------------------------------------------------------------------------------------*/ - return rootTopic; + return seedTopicId >= 0 && topics.TryGetValue(seedTopicId, out var requestedTopic) + ? requestedTopic + : rootTopic; } From f242fcb1cac0bc779cfaa9258f10f385d1e064f0 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sat, 4 Jul 2026 18:53:32 -0700 Subject: [PATCH 056/337] Renamed `boundaries` arguments to `payload` MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Previously, I renamed the `LoadBoundaries` flags enum to `TopicPayload` (07a01cf8). When I did this, however, the `boundaries` parameter continued to be used—and, worse, carried forward. That was sloppy on my part. This fixes that. Note that there are a few places where I'm currently in the process of refactoring—notably, `Topic`, `CachedTopicRepository`, `StubTopicRepository`—and, therefore, am not making that change yet. Those will come shortly. --- OnTopic.Data.Sql/SqlTopicRepository.cs | 52 +++++++++---------- OnTopic.TestDoubles/StubTopicRepository.cs | 6 +-- .../TestDoubles/TrackingTopicLoadResolver.cs | 4 +- OnTopic/Repositories/ITopicLoadResolver.cs | 8 +-- OnTopic/Topic.cs | 16 +++--- 5 files changed, 43 insertions(+), 43 deletions(-) diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index 7a710353..f79b64bc 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -378,7 +378,7 @@ public override void Refresh(Topic referenceTopic, DateTime since) { \---------------------------------------------------------------------------------------------------------------------------*/ /// - public virtual void EnsureLoaded(Topic topic, TopicPayload boundaries) { + public virtual void EnsureLoaded(Topic topic, TopicPayload payload) { /*-------------------------------------------------------------------------------------------------------------------------- | Validate parameters @@ -393,18 +393,18 @@ public virtual void EnsureLoaded(Topic topic, TopicPayload boundaries) { } /*-------------------------------------------------------------------------------------------------------------------------- - | Filter to pending (not yet Loaded) boundaries + | Filter to pending (not yet Loaded) payload \-------------------------------------------------------------------------------------------------------------------------*/ - boundaries = FilterLoadedBoundaries(topic, boundaries); + payload = topic.FilterPayload(payload); - if (boundaries is 0) { + if (payload is TopicPayload.None) { return; } /*-------------------------------------------------------------------------------------------------------------------------- | Children not yet implemented; guard before opening a connection \-------------------------------------------------------------------------------------------------------------------------*/ - if (boundaries.HasFlag(TopicPayload.Children)) { + if (payload.HasFlag(TopicPayload.Children)) { throw new NotImplementedException("Per-level child loading will be implemented in Task 5."); } @@ -417,7 +417,7 @@ public virtual void EnsureLoaded(Topic topic, TopicPayload boundaries) { }; // Set the stored procedure parameters based on the TopicPayload enum values - AddEnsureLoadedParameters(command, topic.Id, boundaries); + AddEnsureLoadedParameters(command, topic.Id, payload); /*-------------------------------------------------------------------------------------------------------------------------- | Process database query @@ -457,13 +457,13 @@ public virtual void EnsureLoaded(Topic topic, TopicPayload boundaries) { } catch (SqlException exception) { - throw new TopicRepositoryException($"Topic boundaries failed to load: '{exception.Message}'", exception); + throw new TopicRepositoryException($"Topic payload failed to load: '{exception.Message}'", exception); } /*-------------------------------------------------------------------------------------------------------------------------- - | Mark loaded boundaries as confirmed + | Mark confirmed payload as Loaded \-------------------------------------------------------------------------------------------------------------------------*/ - MarkBoundariesLoaded(topic, boundaries); + MarkBoundariesLoaded(topic, payload); } @@ -483,18 +483,18 @@ public virtual async Task EnsureLoadedAsync(Topic topic, TopicPayload boundaries } /*-------------------------------------------------------------------------------------------------------------------------- - | Filter to pending (not yet Loaded) boundaries + | Filter to pending (not yet Loaded) payload \-------------------------------------------------------------------------------------------------------------------------*/ - boundaries = FilterLoadedBoundaries(topic, boundaries); + payload = topic.FilterPayload(payload); - if (boundaries is 0) { + if (payload is TopicPayload.None) { return; } /*-------------------------------------------------------------------------------------------------------------------------- | Children not yet implemented; guard before opening a connection \-------------------------------------------------------------------------------------------------------------------------*/ - if (boundaries.HasFlag(TopicPayload.Children)) { + if (payload.HasFlag(TopicPayload.Children)) { throw new NotImplementedException("Per-level child loading will be implemented in Task 5."); } @@ -507,7 +507,7 @@ public virtual async Task EnsureLoadedAsync(Topic topic, TopicPayload boundaries }; // Set the stored procedure parameters based on the TopicPayload enum values - AddEnsureLoadedParameters(command, topic.Id, boundaries); + AddEnsureLoadedParameters(command, topic.Id, payload); /*-------------------------------------------------------------------------------------------------------------------------- | Process database query @@ -547,13 +547,13 @@ public virtual async Task EnsureLoadedAsync(Topic topic, TopicPayload boundaries } catch (SqlException exception) { - throw new TopicRepositoryException($"Topic boundaries failed to load: '{exception.Message}'", exception); + throw new TopicRepositoryException($"Topic payload failed to load: '{exception.Message}'", exception); } /*-------------------------------------------------------------------------------------------------------------------------- - | Mark loaded boundaries as confirmed + | Mark confirmed payload as Loaded \-------------------------------------------------------------------------------------------------------------------------*/ - MarkBoundariesLoaded(topic, boundaries); + MarkBoundariesLoaded(topic, payload); } @@ -878,15 +878,15 @@ private static void MarkBoundariesLoaded(Topic topic, TopicPayload boundaries) { \---------------------------------------------------------------------------------------------------------------------------*/ /// /// Configures a targeting GetTopics for use by the , - /// setting the payload parameters based on the requested . + /// setting the payload parameters based on the requested . /// /// /// Scope is always None (i.e., a single node) for resolver fills, as the caller is already in the graph. is hardcoded to false here because its fill path is not yet implemented; once - /// it is, this method will map it from the flag. Indexed attributes are only requested when + /// it is, this method will map it from the flag. Indexed attributes are only requested when /// filling the boundary. /// - private static void AddEnsureLoadedParameters(SqlCommand command, int topicId, TopicPayload boundaries) { + private static void AddEnsureLoadedParameters(SqlCommand command, int topicId, TopicPayload payload) { // Set the topic we're working with command.AddParameter("TopicID", topicId); @@ -894,13 +894,13 @@ private static void AddEnsureLoadedParameters(SqlCommand command, int topicId, T // Scope: LoadChildren when filling the Children, otherwise we're only interested in this topic's content command.AddParameter("LoadDescendants", false); command.AddParameter("LoadAscendants", false); - command.AddParameter("LoadChildren", boundaries.HasFlag(TopicPayload.Children)); + command.AddParameter("LoadChildren", payload.HasFlag(TopicPayload.Children)); - // Payload: Include only what the requested boundaries require - command.AddParameter("IncludeIndexed", boundaries.HasFlag(TopicPayload.Children)); - command.AddParameter("IncludeExtended", boundaries.HasFlag(TopicPayload.ExtendedAttributes)); - command.AddParameter("IncludeRelationships", boundaries.HasFlag(TopicPayload.Relationships)); - command.AddParameter("IncludeReferences", boundaries.HasFlag(TopicPayload.References)); + // Payload: Include only what the requested payload require + command.AddParameter("IncludeIndexed", payload.HasFlag(TopicPayload.Children)); + command.AddParameter("IncludeExtended", payload.HasFlag(TopicPayload.ExtendedAttributes)); + command.AddParameter("IncludeRelationships", payload.HasFlag(TopicPayload.Relationships)); + command.AddParameter("IncludeReferences", payload.HasFlag(TopicPayload.References)); command.AddParameter("IncludeHistory", false); } diff --git a/OnTopic.TestDoubles/StubTopicRepository.cs b/OnTopic.TestDoubles/StubTopicRepository.cs index c8994638..f7bd0547 100644 --- a/OnTopic.TestDoubles/StubTopicRepository.cs +++ b/OnTopic.TestDoubles/StubTopicRepository.cs @@ -216,7 +216,7 @@ public virtual void EnsureLoaded(Topic topic, TopicPayload boundaries) { Contract.Requires(topic); /*-------------------------------------------------------------------------------------------------------------------------- - | Mark boundaries as loaded; stubs have all relationships and references pre-built in memory, so all targets are resident + | Mark payload as loaded; stubs have all relationships and references pre-built in memory, so all targets are resident | and marking Loaded is always safe. Children is already populated in the stubs and needs no action. \-------------------------------------------------------------------------------------------------------------------------*/ if (boundaries.HasFlag(TopicPayload.ExtendedAttributes) && topic.Attributes.LoadState is LoadState.NotLoaded) { @@ -234,8 +234,8 @@ public virtual void EnsureLoaded(Topic topic, TopicPayload boundaries) { } /// - public virtual Task EnsureLoadedAsync(Topic topic, TopicPayload boundaries, CancellationToken cancellationToken) { - EnsureLoaded(topic, boundaries); + public virtual Task EnsureLoadedAsync(Topic topic, TopicPayload payload, CancellationToken cancellationToken) { + EnsureLoaded(topic, payload); return Task.CompletedTask; } diff --git a/OnTopic.Tests/TestDoubles/TrackingTopicLoadResolver.cs b/OnTopic.Tests/TestDoubles/TrackingTopicLoadResolver.cs index 5fbba101..2c48445f 100644 --- a/OnTopic.Tests/TestDoubles/TrackingTopicLoadResolver.cs +++ b/OnTopic.Tests/TestDoubles/TrackingTopicLoadResolver.cs @@ -29,7 +29,7 @@ internal sealed class TrackingTopicLoadResolver : ITopicLoadResolver { | METHOD: ENSURE LOADED \---------------------------------------------------------------------------------------------------------------------------*/ /// - void ITopicLoadResolver.EnsureLoaded(Topic topic, TopicPayload boundaries) => WasCalled = true; + void ITopicLoadResolver.EnsureLoaded(Topic topic, TopicPayload payload) => WasCalled = true; /*============================================================================================================================ | METHOD: ENSURE LOADED (ASYNC) @@ -37,7 +37,7 @@ internal sealed class TrackingTopicLoadResolver : ITopicLoadResolver { /// Task ITopicLoadResolver.EnsureLoadedAsync( Topic topic, - TopicPayload boundaries, + TopicPayload payload, CancellationToken cancellationToken ) { WasCalled = true; diff --git a/OnTopic/Repositories/ITopicLoadResolver.cs b/OnTopic/Repositories/ITopicLoadResolver.cs index 67cfe21a..f212866b 100644 --- a/OnTopic/Repositories/ITopicLoadResolver.cs +++ b/OnTopic/Repositories/ITopicLoadResolver.cs @@ -10,7 +10,7 @@ namespace OnTopic.Repositories; | INTERFACE: TOPIC LOAD RESOLVER \-----------------------------------------------------------------------------------------------------------------------------*/ /// -/// Provides a narrow seam through which a can populate one or more deferred boundaries on demand, without +/// Provides a narrow seam through which a can populate one or more deferred payload on demand, without /// taking a dependency on the full . Instances are stamped onto topics by the repository as /// they are loaded or saved; topics created in memory carry no resolver. /// @@ -20,13 +20,13 @@ public interface ITopicLoadResolver { | METHOD: ENSURE LOADED \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Ensures each requested flag has been retrieved for the supplied , + /// Ensures each requested flag has been retrieved for the supplied , /// fetching and merging whichever of them are not yet and silently skipping those already /// loaded. Invoked by the autoloading property getters, each with its own flag. /// - void EnsureLoaded(Topic topic, TopicPayload boundaries); + void EnsureLoaded(Topic topic, TopicPayload payload); /// - Task EnsureLoadedAsync(Topic topic, TopicPayload boundaries, CancellationToken cancellationToken = default); + Task EnsureLoadedAsync(Topic topic, TopicPayload payload, CancellationToken cancellationToken = default); } //Interface \ No newline at end of file diff --git a/OnTopic/Topic.cs b/OnTopic/Topic.cs index 293d64b6..7b8bd307 100644 --- a/OnTopic/Topic.cs +++ b/OnTopic/Topic.cs @@ -167,33 +167,33 @@ public Topic? Parent { | METHOD: IS LOADED \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Returns if every boundary flag in has already been fetched from + /// Returns if every boundary flag in has already been fetched from /// the underlying persistence store; if any one of them are . /// /// /// Reads each collection's directly without touching any autoloading getter, making it safe to /// use in traversal and "gating" logic that should not trigger lazy-loading. /// - /// One or more flags to test. - public bool IsLoaded(TopicPayload boundaries) { + /// One or more flags to test. + public bool IsLoaded(TopicPayload payload) { // Children - if (boundaries.HasFlag(TopicPayload.Children) && _children.LoadState is not LoadState.Loaded) { + if (payload.HasFlag(TopicPayload.Children) && _children.LoadState is not LoadState.Loaded) { return false; } // Extended Attributes - if (boundaries.HasFlag(TopicPayload.ExtendedAttributes) && Attributes.LoadState is not LoadState.Loaded) { + if (payload.HasFlag(TopicPayload.ExtendedAttributes) && Attributes.LoadState is not LoadState.Loaded) { return false; } // Relationships - if (boundaries.HasFlag(TopicPayload.Relationships) && Relationships.LoadState is not LoadState.Loaded) { + if (payload.HasFlag(TopicPayload.Relationships) && Relationships.LoadState is not LoadState.Loaded) { return false; } // References - if (boundaries.HasFlag(TopicPayload.References) && References.LoadState is not LoadState.Loaded) { + if (payload.HasFlag(TopicPayload.References) && References.LoadState is not LoadState.Loaded) { return false; } @@ -206,7 +206,7 @@ public bool IsLoaded(TopicPayload boundaries) { | METHODS: ENSURE LOADED \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Ensures each requested flag has been retrieved, while fetching and merging whichever of + /// Ensures each requested flag has been retrieved, while fetching and merging whichever of /// them are not yet , and silently skipping those already are. Returns immediately if the /// resolver is absent or the topic is new. /// From 3e3d53879a12156574ee6475be5ee1cdf2128ce8 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sat, 4 Jul 2026 18:59:06 -0700 Subject: [PATCH 057/337] Introduced `Topic.FilterPayload()` method This will evaluate a `TopicPayload` flags enum against the actual state of the current topic and remove any flags that correspond to parts of the payload that are already fully loaded (i.e., `IsLoaded()`/`LoadState.Loaded`). This will provide a public, centralized version of the private `FilterLoadedBoundaries()` method on `SqlTopicRepository` (31b986a8), which will be removed in a subsequent commit. --- OnTopic/Topic.cs | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/OnTopic/Topic.cs b/OnTopic/Topic.cs index 7b8bd307..bdaae638 100644 --- a/OnTopic/Topic.cs +++ b/OnTopic/Topic.cs @@ -202,6 +202,31 @@ public bool IsLoaded(TopicPayload payload) { } + /*============================================================================================================================ + | METHOD: FILTER PAYLOAD + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Returns with any already- flags cleared, so callers skip + /// redundant round-trips. + /// + /// The requested flags to filter. + public TopicPayload FilterPayload(TopicPayload payload) { + + // Strip already-loaded payload + foreach (var flag in Enum.GetValues()) { + if (flag is TopicPayload.None or TopicPayload.All) { + continue; + } + if (IsLoaded(flag)) { + payload &= ~flag; + } + } + + // Return filtered payload + return payload; + + } + /*============================================================================================================================ | METHODS: ENSURE LOADED \---------------------------------------------------------------------------------------------------------------------------*/ From 3ea5d45a5277eb528d930e90a2e4e073b807b046 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sat, 4 Jul 2026 19:07:18 -0700 Subject: [PATCH 058/337] Implemented `Topic.FilterPayload()` method This implements the new `Topic.FilterPayload()` method (3e3d5387), simplifying the `EnsureLoaded()` and `EnsureLoadedAsync()` calls in `Topic`, `CachedTopicRepository`, `SqlTopicRepository`, and `Topic`. This also completes the renaming of arguments from `boundaries` to `payload` (f242fcb1). Note that the calls in the `SqlTopicRepository` were prematurely committed with that effort; whoops! This cleans up after an effort related to #111. --- OnTopic.Data.Caching/CachedTopicRepository.cs | 32 +++----- OnTopic.Data.Sql/SqlTopicRepository.cs | 29 -------- OnTopic/Topic.cs | 74 +++++-------------- 3 files changed, 27 insertions(+), 108 deletions(-) diff --git a/OnTopic.Data.Caching/CachedTopicRepository.cs b/OnTopic.Data.Caching/CachedTopicRepository.cs index dc1945b7..aa753020 100644 --- a/OnTopic.Data.Caching/CachedTopicRepository.cs +++ b/OnTopic.Data.Caching/CachedTopicRepository.cs @@ -153,7 +153,7 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos \---------------------------------------------------------------------------------------------------------------------------*/ /// - public virtual void EnsureLoaded(Topic topic, TopicPayload boundaries) { + public virtual void EnsureLoaded(Topic topic, TopicPayload payload) { /*-------------------------------------------------------------------------------------------------------------------------- | Validate parameters @@ -161,28 +161,22 @@ public virtual void EnsureLoaded(Topic topic, TopicPayload boundaries) { Contract.Requires(topic); /*-------------------------------------------------------------------------------------------------------------------------- - | Filter to pending (not yet loaded) boundaries + | Filter to pending (not yet Loaded) payload \-------------------------------------------------------------------------------------------------------------------------*/ + payload = topic.FilterPayload(payload); - // Children - if (topic.IsLoaded(TopicPayload.Children)) { - boundaries &= ~TopicPayload.Children; + if (payload is TopicPayload.None) { + return; } - // Extended Attributes - if (topic.IsLoaded(TopicPayload.ExtendedAttributes)) { - boundaries &= ~TopicPayload.ExtendedAttributes; } - // None - if (boundaries is 0) { - return; } } /// - public virtual Task EnsureLoadedAsync(Topic topic, TopicPayload boundaries, CancellationToken cancellationToken) { + public virtual Task EnsureLoadedAsync(Topic topic, TopicPayload payload, CancellationToken cancellationToken) { /*-------------------------------------------------------------------------------------------------------------------------- | Validate parameters @@ -190,22 +184,16 @@ public virtual Task EnsureLoadedAsync(Topic topic, TopicPayload boundaries, Canc Contract.Requires(topic); /*-------------------------------------------------------------------------------------------------------------------------- - | Filter to pending (i.e., not yet Loaded) boundaries + | Filter to pending (i.e., not yet Loaded) payload \-------------------------------------------------------------------------------------------------------------------------*/ + payload = topic.FilterPayload(payload); - // Children - if (topic.IsLoaded(TopicPayload.Children)) { - boundaries &= ~TopicPayload.Children; + if (payload is TopicPayload.None) { + return Task.CompletedTask; } - // Extended Attributes - if (topic.IsLoaded(TopicPayload.ExtendedAttributes)) { - boundaries &= ~TopicPayload.ExtendedAttributes; } - // None - if (boundaries is 0) { - return Task.CompletedTask; } return Task.CompletedTask; diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index f79b64bc..f79a0784 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -905,35 +905,6 @@ private static void AddEnsureLoadedParameters(SqlCommand command, int topicId, T } - /*============================================================================================================================ - | METHOD: FILTER LOADED BOUNDARIES - \---------------------------------------------------------------------------------------------------------------------------*/ - /// - /// Returns with any already- flags cleared, so that and skip redundant round-trips. - /// - private static TopicPayload FilterLoadedBoundaries(Topic topic, TopicPayload boundaries) { - - // Loop through all boundaries - foreach (TopicPayload flag in Enum.GetValues()) { - - // Skip None (0) and All (composite) - if (flag is TopicPayload.None or TopicPayload.All) { - continue; - } - - // Strip the boundary if is is already fully loaded - if (topic.IsLoaded(flag)) { - boundaries &= ~flag; - } - - } - - // Return filtered boundaries - return boundaries; - - } - /*============================================================================================================================ | METHOD: PERSIST RELATIONSHIPS \---------------------------------------------------------------------------------------------------------------------------*/ diff --git a/OnTopic/Topic.cs b/OnTopic/Topic.cs index bdaae638..2d94b866 100644 --- a/OnTopic/Topic.cs +++ b/OnTopic/Topic.cs @@ -237,14 +237,14 @@ public TopicPayload FilterPayload(TopicPayload payload) { /// /// /// The synchronous form backs the autoloading property getters (e.g., the getter); the asynchronous - /// form is for callers, such as a mapping or navigation service, that need to prepopulate one or more boundaries before + /// form is for callers, such as a mapping or navigation service, that need to prepopulate one or more payload before /// accessing them, thus avoiding a synchronous block on a "cold" node. A flag call lets those callers request everything a /// node's mapping needs in a single round trip. /// - /// - /// One or more flags identifying the boundaries that should be ensured to be loaded. + /// + /// One or more flags identifying the payload that should be ensured to be loaded. /// - public void EnsureLoaded(TopicPayload boundaries) { + public void EnsureLoaded(TopicPayload payload) { /*-------------------------------------------------------------------------------------------------------------------------- | Skip for obvious reasons @@ -254,45 +254,25 @@ public void EnsureLoaded(TopicPayload boundaries) { } /*-------------------------------------------------------------------------------------------------------------------------- - | Filter to boundaries that are not yet loaded + | Filter to payload that are not yet loaded \-------------------------------------------------------------------------------------------------------------------------*/ + payload = FilterPayload(payload); - // Children - if (IsLoaded(TopicPayload.Children)) { - boundaries &= ~TopicPayload.Children; - } - - // ExtendedAttributes - if (IsLoaded(TopicPayload.ExtendedAttributes)) { - boundaries &= ~TopicPayload.ExtendedAttributes; - } - - // Relationships - if (IsLoaded(TopicPayload.Relationships)) { - boundaries &= ~TopicPayload.Relationships; - } - - // References - if (IsLoaded(TopicPayload.References)) { - boundaries &= ~TopicPayload.References; - } - - // None - if (boundaries is TopicPayload.None) { + if (payload is TopicPayload.None) { return; } - // Ensure the appropriate boundaries are loaded - _resolver.EnsureLoaded(this, boundaries); + // Ensure the appropriate payload are loaded + _resolver.EnsureLoaded(this, payload); } /// - /// - /// One or more flags identifying the boundaries that should be ensured to be loaded. + /// + /// One or more flags identifying the payload that should be ensured to be loaded. /// /// An optional token that can be used to cancel the operation. - public Task EnsureLoadedAsync(TopicPayload boundaries, CancellationToken cancellationToken = default) { + public Task EnsureLoadedAsync(TopicPayload payload, CancellationToken cancellationToken = default) { /*-------------------------------------------------------------------------------------------------------------------------- | Skip for obvious reasons @@ -302,36 +282,16 @@ public Task EnsureLoadedAsync(TopicPayload boundaries, CancellationToken cancell } /*-------------------------------------------------------------------------------------------------------------------------- - | Filter to boundaries that are not yet loaded + | Filter to payload that are not yet loaded \-------------------------------------------------------------------------------------------------------------------------*/ + payload = FilterPayload(payload); - // Children - if (IsLoaded(TopicPayload.Children)) { - boundaries &= ~TopicPayload.Children; - } - - // Extended Attributes - if (IsLoaded(TopicPayload.ExtendedAttributes)) { - boundaries &= ~TopicPayload.ExtendedAttributes; - } - - // Relationships - if (IsLoaded(TopicPayload.Relationships)) { - boundaries &= ~TopicPayload.Relationships; - } - - // References - if (IsLoaded(TopicPayload.References)) { - boundaries &= ~TopicPayload.References; - } - - // None - if (boundaries is TopicPayload.None) { + if (payload is TopicPayload.None) { return Task.CompletedTask; } - // Ensure the appropriate boundaries are loaded - return _resolver.EnsureLoadedAsync(this, boundaries, cancellationToken); + // Ensure the appropriate payload are loaded + return _resolver.EnsureLoadedAsync(this, payload, cancellationToken); } From 03a1e2464d00632dc677f5aeeab4f3eaf43baab5 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sat, 4 Jul 2026 19:12:29 -0700 Subject: [PATCH 059/337] Introduced `Topic.SetLoadState()` method This is the opposite of `IsLoaded()` (e5ddc2), which determine if any of the potentially deferred sites in `TopicPayload` are `LoadState.NotLoaded`. Instead, this sets the sites corresponding to the `TopicPayload`. This way, callers don't need to know where each of these live, nor worry about whether calling them will trip the lazy-loading (as will happen with `Children`, at minimum), but can just call `SetLoadState()` and it'll handle that for them. This relates to the lazy-loading implementation (#111). --- OnTopic/Topic.cs | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/OnTopic/Topic.cs b/OnTopic/Topic.cs index 2d94b866..9b2d9e49 100644 --- a/OnTopic/Topic.cs +++ b/OnTopic/Topic.cs @@ -202,6 +202,45 @@ public bool IsLoaded(TopicPayload payload) { } + /*============================================================================================================================ + | METHOD: SET LOAD STATE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Sets the for each boundary flag in to . + /// + /// + /// Mirrors : Sets each collection's directly without touching + /// any autoloading getter. Callers are responsible for passing only payload whose transition is safe; for example, and should only be promoted to after confirming all targets are available in the graph, since + /// permits DeleteUnmatched on save. + /// + /// One or more flags identifying the payload to update. + /// The to assign to each matched boundary's collection. + public void SetLoadState(TopicPayload payload, LoadState state) { + + // Children + if (payload.HasFlag(TopicPayload.Children)) { + _children.LoadState = state; + } + + // Extended Attributes + if (payload.HasFlag(TopicPayload.ExtendedAttributes)) { + Attributes.LoadState = state; + } + + // Relationships + if (payload.HasFlag(TopicPayload.Relationships)) { + Relationships.LoadState = state; + } + + // References + if (payload.HasFlag(TopicPayload.References)) { + References.LoadState = state; + } + + } + /*============================================================================================================================ | METHOD: FILTER PAYLOAD \---------------------------------------------------------------------------------------------------------------------------*/ From 5fc6da90ba98dfd6ca320772469d06ae383e9595 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sat, 4 Jul 2026 19:16:16 -0700 Subject: [PATCH 060/337] Implemented `Topic.SetLoadState()` method This implements the new `Topic.SetLoadState()` method (03a1e246), simplifying the `EnsureLoaded()` and `EnsureLoadedAsync()` calls in `SqlTopicRepository` and `StubTopicRepository`. This also completes the renaming of arguments from `boundaries` to `payload` (f242fcb1). Note that at least one of these parameters in `SqlTopicRepository()` was accidentally renamed and prematurely committed with that effort; whoops! This cleans up after an effort related to #111. --- OnTopic.Data.Sql/SqlTopicRepository.cs | 30 +++------------------- OnTopic.TestDoubles/StubTopicRepository.cs | 14 ++-------- 2 files changed, 5 insertions(+), 39 deletions(-) diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index f79a0784..4bdb8e07 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -463,12 +463,12 @@ public virtual void EnsureLoaded(Topic topic, TopicPayload payload) { /*-------------------------------------------------------------------------------------------------------------------------- | Mark confirmed payload as Loaded \-------------------------------------------------------------------------------------------------------------------------*/ - MarkBoundariesLoaded(topic, payload); + topic.SetLoadState(payload & TopicPayload.ExtendedAttributes, LoadState.Loaded); } /// - public virtual async Task EnsureLoadedAsync(Topic topic, TopicPayload boundaries, CancellationToken cancellationToken) { + public virtual async Task EnsureLoadedAsync(Topic topic, TopicPayload payload, CancellationToken cancellationToken) { /*-------------------------------------------------------------------------------------------------------------------------- | Validate parameters @@ -553,7 +553,7 @@ public virtual async Task EnsureLoadedAsync(Topic topic, TopicPayload boundaries /*-------------------------------------------------------------------------------------------------------------------------- | Mark confirmed payload as Loaded \-------------------------------------------------------------------------------------------------------------------------*/ - MarkBoundariesLoaded(topic, payload); + topic.SetLoadState(payload & TopicPayload.ExtendedAttributes, LoadState.Loaded); } @@ -849,30 +849,6 @@ protected override sealed void DeleteTopic(Topic topic) { } - /*============================================================================================================================ - | METHOD: MARK BOUNDARIES LOADED - \---------------------------------------------------------------------------------------------------------------------------*/ - /// - /// Marks each boundary in as on the given after a successful resolver fill. - /// - /// - /// and are intentionally excluded. Their - /// is set by and based on whether each target is resident in the topic graph: a non-resident - /// target sets , which blocks DeleteUnmatched on save and prevents silent data - /// loss. Overwriting that state here, before the resolver has access to the live graph, would defeat that guard. - /// - private static void MarkBoundariesLoaded(Topic topic, TopicPayload boundaries) { - - // Extended attributes: Mark Loaded unconditionally; the whole blob is fetched as a unit and is complete regardless of - // whether related topics are resident - if (boundaries.HasFlag(TopicPayload.ExtendedAttributes)) { - topic.Attributes.LoadState = LoadState.Loaded; - } - - } - /*============================================================================================================================ | METHOD: ADD ENSURE LOADED PARAMETERS \---------------------------------------------------------------------------------------------------------------------------*/ diff --git a/OnTopic.TestDoubles/StubTopicRepository.cs b/OnTopic.TestDoubles/StubTopicRepository.cs index f7bd0547..d699193af 100644 --- a/OnTopic.TestDoubles/StubTopicRepository.cs +++ b/OnTopic.TestDoubles/StubTopicRepository.cs @@ -208,7 +208,7 @@ protected override void SaveTopic([NotNull]Topic topic, DateTime version, bool p /// database. /// /// - public virtual void EnsureLoaded(Topic topic, TopicPayload boundaries) { + public virtual void EnsureLoaded(Topic topic, TopicPayload payload) { /*-------------------------------------------------------------------------------------------------------------------------- | Validate parameters @@ -219,17 +219,7 @@ public virtual void EnsureLoaded(Topic topic, TopicPayload boundaries) { | Mark payload as loaded; stubs have all relationships and references pre-built in memory, so all targets are resident | and marking Loaded is always safe. Children is already populated in the stubs and needs no action. \-------------------------------------------------------------------------------------------------------------------------*/ - if (boundaries.HasFlag(TopicPayload.ExtendedAttributes) && topic.Attributes.LoadState is LoadState.NotLoaded) { - topic.Attributes.LoadState = LoadState.Loaded; - } - - if (boundaries.HasFlag(TopicPayload.Relationships) && topic.Relationships.LoadState is LoadState.NotLoaded) { - topic.Relationships.LoadState = LoadState.Loaded; - } - - if (boundaries.HasFlag(TopicPayload.References) && topic.References.LoadState is LoadState.NotLoaded) { - topic.References.LoadState = LoadState.Loaded; - } + topic.SetLoadState(payload, LoadState.Loaded); } From bdeac02f812d33a7f6d3a59ab69f9a06491b738c Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sat, 4 Jul 2026 19:22:11 -0700 Subject: [PATCH 061/337] Fix test related to `@LoadAscendants` test In a previous update, I fixed a bug in `Load()` and `LoadTopicGraph()` where it returned the root topic, which wasn't necessarily the requested topic (c14bff72). This was due to the fact that I am now conditionally exposing the `@LoadAscendants` parameter of the `GetTopics` stored procedure (19688765), which means the topics returned may not include only the topic you requested, but also its ascendants. In doing so, however, this also broke a new unit test (7da41f55), which had been written with that (faulty) assumption in mind. This fixes that, and tightens up the tests related to #111. --- OnTopic.Tests/SqlTopicRepositoryTest.cs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/OnTopic.Tests/SqlTopicRepositoryTest.cs b/OnTopic.Tests/SqlTopicRepositoryTest.cs index d3c0a236..841032e8 100644 --- a/OnTopic.Tests/SqlTopicRepositoryTest.cs +++ b/OnTopic.Tests/SqlTopicRepositoryTest.cs @@ -611,11 +611,11 @@ public void LoadTopicGraph_WithHasChildrenOnAncestorAndLoadedSubtree_SetsLoadSta // The seed topic is Child (2); Root (1) is on the ancestor chain and is NotLoaded. // The Child (seed) and Grandchild are in the fully loaded subtree and are Loaded. - var rootTopic = tableReader.LoadTopicGraph(2); - var childTopic = rootTopic?.Children.FirstOrDefault(); + var seedTopic = tableReader.LoadTopicGraph(2); + var rootTopic = seedTopic?.Parent; Assert.Equal(LoadState.NotLoaded, rootTopic?.Children.LoadState); - Assert.Equal(LoadState.Loaded, childTopic?.Children.LoadState); + Assert.Equal(LoadState.Loaded, seedTopic?.Children.LoadState); } From 01b04d2c9808df98dfa303a84717de3063adc709 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sat, 4 Jul 2026 19:27:43 -0700 Subject: [PATCH 062/337] Provided note explaining relations exception We don't explicitly `SetLoadState()` of either `Relationships` or `References` as part of `EnsureLoaded()` or `EnsureLoadedAsync()`. This is because we only loaded the IDs, but those iDs could be orphaned if they don't correctly find a reference in the topic graph. The `SetRelationships()` and `SetReferences()` extension methods on the `SqlDataReader` already account for that by setting `LoadState` to `NotLoaded` if that lookup fails for any of them, so we trust that. --- OnTopic.Data.Sql/SqlTopicRepository.cs | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index 4bdb8e07..74ff75cf 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -462,6 +462,10 @@ public virtual void EnsureLoaded(Topic topic, TopicPayload payload) { /*-------------------------------------------------------------------------------------------------------------------------- | Mark confirmed payload as Loaded + >------------------------------------------------------------------------------------------------------------------------- + | Relationships and References are intentionally excluded: Their LoadState is set by SetRelationships()/SetReferences() + | based on whether each target is present in the graph (NotLoaded when a target is absent) which blocks DeleteUnmatched on + | save and prevents silent data loss. Overwriting that guard here would defeat that. \-------------------------------------------------------------------------------------------------------------------------*/ topic.SetLoadState(payload & TopicPayload.ExtendedAttributes, LoadState.Loaded); @@ -552,6 +556,10 @@ public virtual async Task EnsureLoadedAsync(Topic topic, TopicPayload payload, C /*-------------------------------------------------------------------------------------------------------------------------- | Mark confirmed payload as Loaded + >------------------------------------------------------------------------------------------------------------------------- + | Relationships and References are intentionally excluded: Their LoadState is set by SetRelationships()/SetReferences() + | based on whether each target is present in the graph (NotLoaded when a target is absent) which blocks DeleteUnmatched on + | save and prevents silent data loss. Overwriting that guard here would defeat that. \-------------------------------------------------------------------------------------------------------------------------*/ topic.SetLoadState(payload & TopicPayload.ExtendedAttributes, LoadState.Loaded); From c7b356a68e7369830e03202d0eda6735a35620cd Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sat, 4 Jul 2026 19:39:10 -0700 Subject: [PATCH 063/337] Preferred binary arithmetic for flags enum values This updates the `TopicPayload` enum (07a01cf8, a0071d65) to use binary arithmetic, similar to how other enums are handled, such as `Relationships`. --- OnTopic/Repositories/TopicPayload.cs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/OnTopic/Repositories/TopicPayload.cs b/OnTopic/Repositories/TopicPayload.cs index 9ac5133f..86cb3bca 100644 --- a/OnTopic/Repositories/TopicPayload.cs +++ b/OnTopic/Repositories/TopicPayload.cs @@ -41,7 +41,7 @@ public enum TopicPayload { /// /// Extended attributes are loaded alongside the indexed attributes. /// - ExtendedAttributes = 2, + ExtendedAttributes = 1 << 1, /*---------------------------------------------------------------------------------------------------------------------------- | RELATIONSHIPS @@ -49,7 +49,7 @@ public enum TopicPayload { /// /// Relationship targets are included. /// - Relationships = 4, + Relationships = 1 << 2, /*---------------------------------------------------------------------------------------------------------------------------- | REFERENCES @@ -57,7 +57,7 @@ public enum TopicPayload { /// /// Topic reference targets are included. /// - References = 8, + References = 1 << 3, /*---------------------------------------------------------------------------------------------------------------------------- | ALL From 0224cea18c5aa647f5293f12422baba8825d88ff Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sat, 4 Jul 2026 22:10:40 -0700 Subject: [PATCH 064/337] Established `AddChildTopic()` This extends the existing `AddTopic()` to include logic needed for setting the parent and child `LoadState`. This is intended exclusively for the `EnsureLoaded()` process required for lazy-loading (#111), as the core logic of `LoadTopicGraph()` is slightly different in terms of how it needs to handle to load states, as it's optimized for a potentially large batch of hierarchical topics. --- OnTopic.Data.Sql/SqlDataReaderExtensions.cs | 39 +++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs index 3ab08982..276fbf2e 100644 --- a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs +++ b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs @@ -491,6 +491,45 @@ internal static void SetReferences(this IDataReader reader, TopicIndex topics, b } + + /*============================================================================================================================ + | METHOD: ADD CHILD TOPIC + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Processes a single row from the children result set of a GetTopics response: Adds the child to the index via , then stamps its Attributes.LoadState and Children.LoadState + /// based on the HasExtendedAttributes and HasChildren database hints. Returns + /// when the row represents the itself (which the stored procedure includes alongside its + /// children) so callers can skip it. + /// + /// The , positioned at a row in the children result set. + /// The topic whose children are being loaded; rows matching this ID are skipped. + /// The to populate. + private static Topic? AddChildTopic(this IDataReader reader, Topic parent, TopicIndex topics) { + + // Add or update the topic in the index + var addedTopic = reader.AddTopic(topics, markDirty: false); + + // Skip the parent record, which the stored procedure returns alongside its children + if (addedTopic.Id == parent.Id) { + return null; + } + + // Set the extended-attribute load state based on the database hint + if (reader.GetNullableBoolean("HasExtendedAttributes") is true) { + addedTopic.Attributes.LoadState = LoadState.NotLoaded; + } + + // Set the children load state based on the database hint + addedTopic.Children.LoadState = reader.GetNullableBoolean("HasChildren") is true + ? LoadState.NotLoaded + : LoadState.Loaded; + + // Return the topic created + return addedTopic; + + } + /*============================================================================================================================ | METHOD: SET VERSION HISTORY \---------------------------------------------------------------------------------------------------------------------------*/ From f7fc2669f26d079497422308216e37ecfddeb286 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sat, 4 Jul 2026 22:14:13 -0700 Subject: [PATCH 065/337] Established `FillChildren[Async]()` extensions These utilize the new `AddChildTopic()` private helper (0224cea1) to provide an internal entry point that `EnsureLoaded()` and `EnsureLoadedAsync()` can call from the `SqlTopicRepository`, thus preparing for one of the key components of the lazy-loading project (#111). --- OnTopic.Data.Sql/SqlDataReaderExtensions.cs | 44 +++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs index 276fbf2e..7d21308e 100644 --- a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs +++ b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs @@ -7,6 +7,7 @@ using System.Net; using OnTopic.Collections.Specialized; using OnTopic.Querying; +using OnTopic.Repositories; namespace OnTopic.Data.Sql; @@ -259,6 +260,49 @@ private static Topic AddTopic(this IDataReader reader, TopicIndex topics, bool? } + /*============================================================================================================================ + | METHOD: FILL CHILDREN + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Reads the children result set (the first result set) from a GetTopics response, adds each child to the index via , and marks the 's Children as after a successful fill. + /// + /// + /// The , positioned at the first result set of the GetTopics response. + /// + /// The topic whose immediate children are being loaded. + /// The to populate with the new child topics. + internal static void FillChildren(this IDataReader reader, Topic parent, TopicIndex topics) { + + // Loop through each record, delegating to the shared AddChildTopic() + while (reader.Read()) { + reader.AddChildTopic(parent, topics); + } + + // Mark confirmed children payload as Loaded + parent.SetLoadState(TopicPayload.Children, LoadState.Loaded); + + } + + /// + internal static async Task FillChildrenAsync( + this SqlDataReader reader, + Topic parent, + TopicIndex topics, + CancellationToken cancellationToken + ) { + + // Loop through each record, delegating to the shared AddChildTopic() + while (await reader.ReadAsync(cancellationToken).ConfigureAwait(false)) { + reader.AddChildTopic(parent, topics); + } + + // Mark confirmed children payload as Loaded + parent.SetLoadState(TopicPayload.Children, LoadState.Loaded); + + } + /*============================================================================================================================ | METHOD: SET INDEXED ATTRIBUTES \---------------------------------------------------------------------------------------------------------------------------*/ From 26377149d25a48a1de395014946eb9bc6c986941 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sat, 4 Jul 2026 22:57:59 -0700 Subject: [PATCH 066/337] Wired up full processing of `GetTopics` payload The `EnsureLoaded()` and `EnsureLoadedAsync()` now fully process all result sets from the `GetTopics` stored procedure, including any children returned via the new `FillChildren[Async]()` extension methods (f7fc2669, 0224cea1). This required making `SetIndexedAttributes()` internal so that it could be called from `SqlTopicRepository()`. The analogous methods for the other payloads were previously marked `internal` (3e84eabd). To fulfill the commitment of the lazy-loading, we'll still need to trigger a queue of `GetTopics` runs for any unmatched Relationships and References, but for now the top priority was getting children supported. --- OnTopic.Data.Sql/SqlDataReaderExtensions.cs | 2 +- OnTopic.Data.Sql/SqlTopicRepository.cs | 70 +++++++++++---------- 2 files changed, 39 insertions(+), 33 deletions(-) diff --git a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs index 7d21308e..1e99035e 100644 --- a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs +++ b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs @@ -318,7 +318,7 @@ CancellationToken cancellationToken /// behavior is overwritten to accept whatever value is submitted. This can be used, for instance, to prevent an update /// from being persisted to the data store on . /// - private static void SetIndexedAttributes(this IDataReader reader, TopicIndex topics, bool? markDirty) { + internal static void SetIndexedAttributes(this IDataReader reader, TopicIndex topics, bool? markDirty) { /*-------------------------------------------------------------------------------------------------------------------------- | Identify attributes diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index 74ff75cf..8a3bb04b 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -395,19 +395,12 @@ public virtual void EnsureLoaded(Topic topic, TopicPayload payload) { /*-------------------------------------------------------------------------------------------------------------------------- | Filter to pending (not yet Loaded) payload \-------------------------------------------------------------------------------------------------------------------------*/ - payload = topic.FilterPayload(payload); + payload = topic.FilterPayload(payload); if (payload is TopicPayload.None) { return; } - /*-------------------------------------------------------------------------------------------------------------------------- - | Children not yet implemented; guard before opening a connection - \-------------------------------------------------------------------------------------------------------------------------*/ - if (payload.HasFlag(TopicPayload.Children)) { - throw new NotImplementedException("Per-level child loading will be implemented in Task 5."); - } - /*-------------------------------------------------------------------------------------------------------------------------- | Establish database connection \-------------------------------------------------------------------------------------------------------------------------*/ @@ -422,19 +415,28 @@ public virtual void EnsureLoaded(Topic topic, TopicPayload payload) { /*-------------------------------------------------------------------------------------------------------------------------- | Process database query \-------------------------------------------------------------------------------------------------------------------------*/ + var topics = new TopicIndex { [topic.Id] = topic }; + try { // Setup connection.Open(); - var topics = new TopicIndex { [topic.Id] = topic }; using var reader = command.ExecuteReader(); - // Skip key-attributes result set; these were populated when the topic was first loaded - reader.NextResult(); + // Children: Fill first result set; FillChildren() sets each child's Children.LoadState and marks the parent as Loaded + if (payload.HasFlag(TopicPayload.Children)) { + reader.FillChildren(topic, topics); + } - // Indexed attributes (will be populated when Children boundary is implemented) - while (reader.Read()) { + // Otherwise, skip the first result set since the topic is already resident + else { + reader.NextResult(); + } + // Indexed attributes + reader.NextResult(); + while (reader.Read()) { + reader.SetIndexedAttributes(topics, markDirty: false); } // Extended attributes @@ -462,10 +464,11 @@ public virtual void EnsureLoaded(Topic topic, TopicPayload payload) { /*-------------------------------------------------------------------------------------------------------------------------- | Mark confirmed payload as Loaded - >------------------------------------------------------------------------------------------------------------------------- - | Relationships and References are intentionally excluded: Their LoadState is set by SetRelationships()/SetReferences() - | based on whether each target is present in the graph (NotLoaded when a target is absent) which blocks DeleteUnmatched on - | save and prevents silent data loss. Overwriting that guard here would defeat that. + >--------------------------------------------------------------------------------------------------------------------------- + | Children is excluded: its LoadState is set inside FillChildren() after a successful fill, with each child's own + | Children.LoadState set based on its HasChildren bit. Relationships and References are excluded: their LoadState is set by + | SetRelationships() / SetReferences() based on whether each target is present in the graph (NotLoaded when absent), which + | blocks DeleteUnmatched on save and prevents silent data loss. \-------------------------------------------------------------------------------------------------------------------------*/ topic.SetLoadState(payload & TopicPayload.ExtendedAttributes, LoadState.Loaded); @@ -495,13 +498,6 @@ public virtual async Task EnsureLoadedAsync(Topic topic, TopicPayload payload, C return; } - /*-------------------------------------------------------------------------------------------------------------------------- - | Children not yet implemented; guard before opening a connection - \-------------------------------------------------------------------------------------------------------------------------*/ - if (payload.HasFlag(TopicPayload.Children)) { - throw new NotImplementedException("Per-level child loading will be implemented in Task 5."); - } - /*-------------------------------------------------------------------------------------------------------------------------- | Establish database connection \-------------------------------------------------------------------------------------------------------------------------*/ @@ -516,19 +512,28 @@ public virtual async Task EnsureLoadedAsync(Topic topic, TopicPayload payload, C /*-------------------------------------------------------------------------------------------------------------------------- | Process database query \-------------------------------------------------------------------------------------------------------------------------*/ + var topics = new TopicIndex { [topic.Id] = topic }; + try { // Setup await connection.OpenAsync(cancellationToken).ConfigureAwait(false); - var topics = new TopicIndex { [topic.Id] = topic }; using var reader = (SqlDataReader)await command.ExecuteReaderAsync(cancellationToken).ConfigureAwait(false); - // Skip key-attributes result set; these were populated when the topic was first loaded - await reader.NextResultAsync(cancellationToken).ConfigureAwait(false); + // Children: Fill first result set; FillChildren() sets each child's Children.LoadState and marks the parent as Loaded + if (payload.HasFlag(TopicPayload.Children)) { + await reader.FillChildrenAsync(topic, topics, cancellationToken).ConfigureAwait(false); + } - // Indexed attributes (will be populated when Children boundary is implemented) - while (await reader.ReadAsync(cancellationToken).ConfigureAwait(false)) { + // Otherwise, skip the first result set since the topic is already resident + else { + await reader.NextResultAsync(cancellationToken).ConfigureAwait(false); + } + // Indexed attributes + await reader.NextResultAsync(cancellationToken).ConfigureAwait(false); + while (await reader.ReadAsync(cancellationToken).ConfigureAwait(false)) { + reader.SetIndexedAttributes(topics, markDirty: false); } // Extended attributes @@ -557,9 +562,10 @@ public virtual async Task EnsureLoadedAsync(Topic topic, TopicPayload payload, C /*-------------------------------------------------------------------------------------------------------------------------- | Mark confirmed payload as Loaded >------------------------------------------------------------------------------------------------------------------------- - | Relationships and References are intentionally excluded: Their LoadState is set by SetRelationships()/SetReferences() - | based on whether each target is present in the graph (NotLoaded when a target is absent) which blocks DeleteUnmatched on - | save and prevents silent data loss. Overwriting that guard here would defeat that. + | Children is excluded: its LoadState is set inside FillChildrenAsync() after a successful fill, with each child's own + | Children.LoadState set based on its HasChildren bit. Relationships and References are excluded: their LoadState is set by + | SetRelationships() / SetReferences() based on whether each target is present in the graph (NotLoaded when absent), which + | blocks DeleteUnmatched on save and prevents silent data loss. \-------------------------------------------------------------------------------------------------------------------------*/ topic.SetLoadState(payload & TopicPayload.ExtendedAttributes, LoadState.Loaded); From f50cd8ba783426cd96d75b1c0cbeb7325218375a Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sun, 5 Jul 2026 17:09:56 -0700 Subject: [PATCH 067/337] Locked calls to index; centralized adds MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Since we have—and will have more—multiple items writing to the `_topicIdIndex` and `_topicKeyIndex`—previously the `_topicById` and `_topicByKey` (22161b12)—on what is effectively treated as a singleton (in DI terms), we need to make sure we're locking references to it. While I was at it, I also introduced a new `IndexTopic()` helper method. This is only needed a couple of times now, but will prove (only slightly) more useful in subsequent updates. This contributes indirectly to #111. --- OnTopic.Data.Caching/CachedTopicRepository.cs | 68 +++++++++++++------ 1 file changed, 49 insertions(+), 19 deletions(-) diff --git a/OnTopic.Data.Caching/CachedTopicRepository.cs b/OnTopic.Data.Caching/CachedTopicRepository.cs index aa753020..77bb0344 100644 --- a/OnTopic.Data.Caching/CachedTopicRepository.cs +++ b/OnTopic.Data.Caching/CachedTopicRepository.cs @@ -26,8 +26,9 @@ public class CachedTopicRepository : TopicRepositoryDecorator, ITopicLoadResolve | VARIABLES \---------------------------------------------------------------------------------------------------------------------------*/ private readonly Topic _cache; - private readonly Dictionary _topicById = new(); - private readonly Dictionary _topicByKey = new(StringComparer.OrdinalIgnoreCase); + private readonly Dictionary _topicIdIndex = new(); + private readonly Dictionary _topicKeyIndex = new(StringComparer.OrdinalIgnoreCase); + private readonly object _syncLock = new(); /*============================================================================================================================ | CONSTRUCTOR @@ -62,8 +63,7 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos | Populate flat index from loaded graph \-------------------------------------------------------------------------------------------------------------------------*/ foreach (var topic in _cache.FindAll()) { - _topicById[topic.Id] = topic; - _topicByKey[topic.GetUniqueKey()] = topic; + IndexTopic(topic); } /*-------------------------------------------------------------------------------------------------------------------------- @@ -94,8 +94,11 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos /*-------------------------------------------------------------------------------------------------------------------------- | Lookup by topic identifier \-------------------------------------------------------------------------------------------------------------------------*/ - _topicById.TryGetValue(topicId, out var topic); - return topic; + lock (_syncLock) { + if (_topicIdIndex.TryGetValue(topicId, out var topic)) { + return topic; + } + } } @@ -117,8 +120,11 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos /*-------------------------------------------------------------------------------------------------------------------------- | Lookup by unique key \-------------------------------------------------------------------------------------------------------------------------*/ - _topicByKey.TryGetValue(uniqueKey, out var topic); - return topic; + lock (_syncLock) { + if (_topicKeyIndex.TryGetValue(uniqueKey, out var topic)) { + return topic; + } + } } @@ -217,9 +223,12 @@ protected override void OnTopicSaved(TopicSaveEventArgs args) { // Index newly created topics and, when saved recursively, any new descendants if (args.IsNew) { - foreach (var topic in args.Topic.FindAll()) { - _topicById[topic.Id] = topic; - _topicByKey[topic.GetUniqueKey()] = topic; + lock (_syncLock) { + foreach (var topic in args.Topic.FindAll()) { + IndexTopic(topic); + _absentTopicIdIndex.Remove(topic.Id); + _absentUniqueKeyIndex.Remove(topic.GetUniqueKey()); + } } } @@ -238,9 +247,11 @@ protected override void OnTopicDeleted(TopicEventArgs args) { base.OnTopicDeleted(args); // Remove the deleted subtree from both indices - foreach (var topic in args.Topic.FindAll()) { - _topicById.Remove(topic.Id); - _topicByKey.Remove(topic.GetUniqueKey()); + lock (_syncLock) { + foreach (var topic in args.Topic.FindAll()) { + _topicIdIndex.Remove(topic.Id); + _topicKeyIndex.Remove(topic.GetUniqueKey()); + } } } @@ -303,11 +314,30 @@ private void RekeyTopicSubtree(Topic topic, string oldRootUniqueKey) { var newRootUniqueKey = topic.GetUniqueKey(); // Remove each stale unique-key entry and replace it with the current unique key - foreach (var subtopic in topic.FindAll()) { - var currentKey = subtopic.GetUniqueKey(); - var oldKey = oldRootUniqueKey + currentKey[newRootUniqueKey.Length..]; - _topicByKey.Remove(oldKey); - _topicByKey[currentKey] = subtopic; + lock (_syncLock) { + foreach (var subtopic in topic.FindAll()) { + var currentKey = subtopic.GetUniqueKey(); + var oldKey = oldRootUniqueKey + currentKey[newRootUniqueKey.Length..]; + _topicKeyIndex.Remove(oldKey); + _topicKeyIndex[currentKey] = subtopic; + } + } + + } + + /*============================================================================================================================ + | METHOD: INDEX TOPIC + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Adds or updates in both flat indexes. + /// + /// + /// Callers are responsible for holding before invoking this method, except during construction + /// where single-threaded access is guaranteed. + /// + private void IndexTopic(Topic topic) { + _topicIdIndex[topic.Id] = topic; + _topicKeyIndex[topic.GetUniqueKey()] = topic; } } From 599c5bef6775dca5fdb5ca213846b1bcacfa19e0 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sun, 5 Jul 2026 17:29:18 -0700 Subject: [PATCH 068/337] Active load cache misses If a `topicID` or `topicKey` is requested that isn't in the cache (22161b12, f50cd8ba) then request it from the database. The `CachedTopicRepository` should never gate the underlying repository to prevent legitimate, specific requests from returning. This is a core assurance of the lazy-loading project (#111). --- OnTopic.Data.Caching/CachedTopicRepository.cs | 96 ++++++++++++++++++- 1 file changed, 95 insertions(+), 1 deletion(-) diff --git a/OnTopic.Data.Caching/CachedTopicRepository.cs b/OnTopic.Data.Caching/CachedTopicRepository.cs index 77bb0344..ebe3eff2 100644 --- a/OnTopic.Data.Caching/CachedTopicRepository.cs +++ b/OnTopic.Data.Caching/CachedTopicRepository.cs @@ -77,6 +77,10 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos | METHOD: LOAD \---------------------------------------------------------------------------------------------------------------------------*/ /// + /// + /// Returns the cached topic if present. On a miss, falls through to the underlying repository with @LoadAscendants + /// enabled so the full ancestor chain is fetched and merged into the live graph. + /// public override Topic? Load( int topicId, Topic? referenceTopic = null, @@ -92,7 +96,7 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos } /*-------------------------------------------------------------------------------------------------------------------------- - | Lookup by topic identifier + | Lookup by topic identifier; return immediately on a hit \-------------------------------------------------------------------------------------------------------------------------*/ lock (_syncLock) { if (_topicIdIndex.TryGetValue(topicId, out var topic)) { @@ -100,9 +104,27 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos } } + /*-------------------------------------------------------------------------------------------------------------------------- + | On miss: Load with ancestors and merge result into the live graph + \-------------------------------------------------------------------------------------------------------------------------*/ + var loaded = TopicRepository.Load(topicId, referenceTopic: null, isRecursive: false); + + // Merge the returned ancestor chain into the cache, rewiring new topics to existing cache objects + MergeIntoCache(loaded); + + // Return the topic from the cache + lock (_syncLock) { + _topicIdIndex.TryGetValue(topicId, out var result); + return result; + } + } /// + /// + /// Returns the cached topic if present. On a miss, falls through to the underlying repository with @LoadAscendants + /// enabled so the full ancestor chain is fetched and merged into the live graph. + /// public override Topic? Load( string uniqueKey, Topic? referenceTopic = null, @@ -126,6 +148,19 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos } } + /*-------------------------------------------------------------------------------------------------------------------------- + | On miss: Load with ancestors and merge result into the live graph + \-------------------------------------------------------------------------------------------------------------------------*/ + var loaded = TopicRepository.Load(uniqueKey, referenceTopic: null, isRecursive: false); + + // Merge the returned ancestor chain into the cache, rewiring new topics to existing cache objects + MergeIntoCache(loaded); + + lock (_syncLock) { + _topicKeyIndex.TryGetValue(uniqueKey, out var result); + return result; + } + } /// @@ -338,6 +373,65 @@ private void RekeyTopicSubtree(Topic topic, string oldRootUniqueKey) { private void IndexTopic(Topic topic) { _topicIdIndex[topic.Id] = topic; _topicKeyIndex[topic.GetUniqueKey()] = topic; + } + + /*============================================================================================================================ + | METHOD: MERGE INTO CACHE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Merges a freshly-loaded ancestor chain into the live graph by rewiring each new topic's to + /// the corresponding cache object, then indexing and resolver-stamping any topics that were not previously resident. + /// + /// + /// + /// Called by the and overloads when a requested topic is not present in the flat index and + /// must be fetched from the underlying with @LoadAscendants = true. The load + /// returns a freshly-built graph, including duplicate objects for ancestors already in the cache. + /// This method replaces each duplicate ancestor with the resident cache object, keeps only genuinely new nodes, and + /// integrates them into the live graph. + /// + /// + /// The chain is walked from the leaf toward the root. At the first ancestor already present in _topicById + /// (typically Root), the new node above it is discarded and its child is reparented to the cached object, which + /// attaches it to the existing graph. All new nodes below that boundary are indexed and stamped with the resolver so + /// their own can lazy-load on demand. + /// + /// + /// The leaf topic returned from the underlying load, already part of an ancestor chain. + private void MergeIntoCache(Topic loaded) { + + // Build the ancestor chain from the leaf up to the root (leaf first) + var chain = new List(); + for (var node = loaded; node is not null; node = node.Parent) { + chain.Add(node); + } + + // Walk the chain leaf-to-root, rewiring new topics onto the existing cache and indexing them + foreach (var node in chain) { + + // Skip topics that are already present in the cache + lock (_syncLock) { + if (_topicIdIndex.ContainsKey(node.Id)) { + continue; + } + } + + // Rewire to the existing cache parent to prevent duplicate Topic objects in the graph + if (node.Parent is not null) { + lock (_syncLock) { + if (_topicIdIndex.TryGetValue(node.Parent.Id, out var cacheParent) && cacheParent != node.Parent) { + node.Parent = cacheParent; + } + } + } + + // Index the new topic and stamp it with the resolver for future lazy fills + lock (_syncLock) { + IndexTopic(node); + } + StampResolver(node); + } } From 06cae07e6e1fa0590b8b331dd11efbedfe12e1a1 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sun, 5 Jul 2026 17:32:24 -0700 Subject: [PATCH 069/337] Establish cache for missing keys In the previous commit, I introduced the ability to actively load cache misses (599c5bef). But we don't want to do that repeatedly if it's also a database miss! So the `_absentTopicIdIndex` and `_absentUniqueKeyIndex` guard against that by tracking cases where the ID or Key was looked up, and failed. This contributes, indirectly, to #111. --- OnTopic.Data.Caching/CachedTopicRepository.cs | 43 ++++++++++++++++++- 1 file changed, 42 insertions(+), 1 deletion(-) diff --git a/OnTopic.Data.Caching/CachedTopicRepository.cs b/OnTopic.Data.Caching/CachedTopicRepository.cs index ebe3eff2..403f0f2f 100644 --- a/OnTopic.Data.Caching/CachedTopicRepository.cs +++ b/OnTopic.Data.Caching/CachedTopicRepository.cs @@ -28,6 +28,8 @@ public class CachedTopicRepository : TopicRepositoryDecorator, ITopicLoadResolve private readonly Topic _cache; private readonly Dictionary _topicIdIndex = new(); private readonly Dictionary _topicKeyIndex = new(StringComparer.OrdinalIgnoreCase); + private readonly HashSet _absentTopicIdIndex = new(); + private readonly HashSet _absentUniqueKeyIndex = new(StringComparer.OrdinalIgnoreCase); private readonly object _syncLock = new(); /*============================================================================================================================ @@ -80,6 +82,8 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos /// /// Returns the cached topic if present. On a miss, falls through to the underlying repository with @LoadAscendants /// enabled so the full ancestor chain is fetched and merged into the live graph. + /// Missing IDs are recorded to prevent + /// redundant round-trips for topics that genuinely do not exist. /// public override Topic? Load( int topicId, @@ -104,11 +108,28 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos } } + /*-------------------------------------------------------------------------------------------------------------------------- + | Skip IDs that are known to be missing to avoid redundant round-trips + \-------------------------------------------------------------------------------------------------------------------------*/ + lock (_syncLock) { + if (_absentTopicIdIndex.Contains(topicId)) { + return null; + } + } + /*-------------------------------------------------------------------------------------------------------------------------- | On miss: Load with ancestors and merge result into the live graph \-------------------------------------------------------------------------------------------------------------------------*/ var loaded = TopicRepository.Load(topicId, referenceTopic: null, isRecursive: false); + // If it's missing, populate the appropriate index so we don't try loading it again + if (loaded is null) { + lock (_syncLock) { + _absentTopicIdIndex.Add(topicId); + } + return null; + } + // Merge the returned ancestor chain into the cache, rewiring new topics to existing cache objects MergeIntoCache(loaded); @@ -124,6 +145,8 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos /// /// Returns the cached topic if present. On a miss, falls through to the underlying repository with @LoadAscendants /// enabled so the full ancestor chain is fetched and merged into the live graph. + /// Missing IDs are recorded to prevent + /// redundant round-trips for topics that genuinely do not exist. /// public override Topic? Load( string uniqueKey, @@ -148,11 +171,27 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos } } + /*-------------------------------------------------------------------------------------------------------------------------- + | Skip IDs that are known to be missing to avoid redundant round-trips + \-------------------------------------------------------------------------------------------------------------------------*/ + lock (_syncLock) { + if (_absentUniqueKeyIndex.Contains(uniqueKey)) { + return null; + } + } + /*-------------------------------------------------------------------------------------------------------------------------- | On miss: Load with ancestors and merge result into the live graph \-------------------------------------------------------------------------------------------------------------------------*/ var loaded = TopicRepository.Load(uniqueKey, referenceTopic: null, isRecursive: false); + if (loaded is null) { + lock (_syncLock) { + _absentUniqueKeyIndex.Add(uniqueKey); + } + return null; + } + // Merge the returned ancestor chain into the cache, rewiring new topics to existing cache objects MergeIntoCache(loaded); @@ -248,7 +287,9 @@ public virtual Task EnsureLoadedAsync(Topic topic, TopicPayload payload, Cancell /// /// /// Adds newly-created topics to the flat index. When the save is recursive, all resident descendants are indexed as well, - /// since only one event fires for the root of a recursive save. + /// since only one event fires for the root of a recursive save. Also clears any + /// entries known to be missing so that a previously missing ID or key that is now created can be found on subsequent + /// lookups. /// protected override void OnTopicSaved(TopicSaveEventArgs args) { From a31a054e4c05eb5df667cbd9593d58d06e04a3e9 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sun, 5 Jul 2026 17:43:57 -0700 Subject: [PATCH 070/337] Normalize lookup of `uniqueKey` The original implementation of `uniqueKey` expects an exact match. But we generally accept the `root:` as optional. This accounts for that. Further, instead of hard-coding `root:`, it looks it up dynamically from the `_cache` root, which should always be the _actual_ root, since even if a subtree was requested, it will have included ancestors by default (19688765). This helps avoid cache misses. This indirectly relates to #111. --- OnTopic.Data.Caching/CachedTopicRepository.cs | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/OnTopic.Data.Caching/CachedTopicRepository.cs b/OnTopic.Data.Caching/CachedTopicRepository.cs index 403f0f2f..01be3407 100644 --- a/OnTopic.Data.Caching/CachedTopicRepository.cs +++ b/OnTopic.Data.Caching/CachedTopicRepository.cs @@ -163,7 +163,17 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos } /*-------------------------------------------------------------------------------------------------------------------------- - | Lookup by unique key + | Normalize key: Accept partial paths such as "Web:Valid:Child" in addition to the canonical "Root:Web:Valid:Child" + \-------------------------------------------------------------------------------------------------------------------------*/ + if ( + !uniqueKey.StartsWith(_cache.Key + ":", StringComparison.OrdinalIgnoreCase) && + !uniqueKey.Equals(_cache.Key, StringComparison.OrdinalIgnoreCase) + ) { + uniqueKey = $"{_cache.Key}:{uniqueKey.TrimStart(':')}"; + } + + /*-------------------------------------------------------------------------------------------------------------------------- + | Lookup by unique key; return immediately on a hit \-------------------------------------------------------------------------------------------------------------------------*/ lock (_syncLock) { if (_topicKeyIndex.TryGetValue(uniqueKey, out var topic)) { From 3cc30d42f49b889846b5ac67e476550c0890f3ce Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sun, 5 Jul 2026 17:47:51 -0700 Subject: [PATCH 071/337] Delegate to inner `resolver`'s `EnsureLoaded()` This corresponds to the active loading of cache misses (599c5bef), but for `EnsureLoading()` instead of `Load()`, thus ensuring the contract of lazy-loading (#111) guaranteeing that the missing data will be made available. --- OnTopic.Data.Caching/CachedTopicRepository.cs | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/OnTopic.Data.Caching/CachedTopicRepository.cs b/OnTopic.Data.Caching/CachedTopicRepository.cs index 01be3407..829b0c38 100644 --- a/OnTopic.Data.Caching/CachedTopicRepository.cs +++ b/OnTopic.Data.Caching/CachedTopicRepository.cs @@ -259,6 +259,11 @@ public virtual void EnsureLoaded(Topic topic, TopicPayload payload) { return; } + /*-------------------------------------------------------------------------------------------------------------------------- + | Delegate to inner resolver + \-------------------------------------------------------------------------------------------------------------------------*/ + if (TopicRepository is ITopicLoadResolver resolver) { + resolver.EnsureLoaded(topic, payload); } } @@ -282,6 +287,11 @@ public virtual Task EnsureLoadedAsync(Topic topic, TopicPayload payload, Cancell return Task.CompletedTask; } + /*-------------------------------------------------------------------------------------------------------------------------- + | Delegate to inner resolver + \-------------------------------------------------------------------------------------------------------------------------*/ + if (TopicRepository is ITopicLoadResolver resolver) { + resolver.EnsureLoaded(topic, payload); } } From 78b314bdf458e1af307737120027a2be6c5b9337 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sun, 5 Jul 2026 17:49:43 -0700 Subject: [PATCH 072/337] Ensure any children loaded are "stamped" If the `EnsureLoaded[Async]()` method loaded new children (via `TopicPayload.Children`), ensure that they're all "stamped" with the `ITopicLoadResolver` so that they can dynamically load any missing dependencies as well. This contributes to #111. --- OnTopic.Data.Caching/CachedTopicRepository.cs | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/OnTopic.Data.Caching/CachedTopicRepository.cs b/OnTopic.Data.Caching/CachedTopicRepository.cs index 829b0c38..8a3d2484 100644 --- a/OnTopic.Data.Caching/CachedTopicRepository.cs +++ b/OnTopic.Data.Caching/CachedTopicRepository.cs @@ -266,6 +266,14 @@ public virtual void EnsureLoaded(Topic topic, TopicPayload payload) { resolver.EnsureLoaded(topic, payload); } + // Update flat index and stamp resolver for any newly loaded children + if (payload.HasFlag(TopicPayload.Children)) { + lock (_syncLock) { + foreach (var child in topic.Children) { + IndexTopic(child); + } + } + StampResolver(topic); } } @@ -294,6 +302,14 @@ public virtual Task EnsureLoadedAsync(Topic topic, TopicPayload payload, Cancell resolver.EnsureLoaded(topic, payload); } + // Update flat index and stamp resolver for any newly loaded children + if (payload.HasFlag(TopicPayload.Children)) { + lock (_syncLock) { + foreach (var child in topic.Children) { + IndexTopic(child); + } + } + StampResolver(topic); } return Task.CompletedTask; From dd0c251499fddeb611adf059bcbd6ce7f80e5f9a Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sun, 5 Jul 2026 17:52:19 -0700 Subject: [PATCH 073/337] Seed cache with bare root, and full configuration Update the `CachedTopicRepository` to seed itself with just the bare `Root` topic` (with no children) but an eager load of `Root:Configuration` (since that will be commonly referenced, and includes a lot of relationships, references that require a full graph to connect). This is a key implementation detail for lazy-loading (#111). --- OnTopic.Data.Caching/CachedTopicRepository.cs | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/OnTopic.Data.Caching/CachedTopicRepository.cs b/OnTopic.Data.Caching/CachedTopicRepository.cs index 8a3d2484..117d4a7b 100644 --- a/OnTopic.Data.Caching/CachedTopicRepository.cs +++ b/OnTopic.Data.Caching/CachedTopicRepository.cs @@ -46,9 +46,9 @@ public class CachedTopicRepository : TopicRepositoryDecorator, ITopicLoadResolve public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepository) { /*-------------------------------------------------------------------------------------------------------------------------- - | Ensure topics are loaded + | Seed root topic (without descendants) \-------------------------------------------------------------------------------------------------------------------------*/ - var rootTopic = TopicRepository.Load(); + var rootTopic = TopicRepository.Load("Root", referenceTopic: null, isRecursive: false); Contract.Assume( rootTopic, @@ -62,7 +62,12 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos _cache = rootTopic; /*-------------------------------------------------------------------------------------------------------------------------- - | Populate flat index from loaded graph + | Eager-load Root:Configuration subtree (required for content-type descriptor resolution) + \-------------------------------------------------------------------------------------------------------------------------*/ + TopicRepository.Load("Root:Configuration", referenceTopic: _cache, isRecursive: true, payload: TopicPayload.All); + + /*-------------------------------------------------------------------------------------------------------------------------- + | Populate flat index from seeded topics \-------------------------------------------------------------------------------------------------------------------------*/ foreach (var topic in _cache.FindAll()) { IndexTopic(topic); From 4c14f312cf186b4e6173986e2d99996d0de6a40e Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sun, 5 Jul 2026 17:52:39 -0700 Subject: [PATCH 074/337] Minor cleanup of `CachedTopicRepository` --- OnTopic.Data.Caching/CachedTopicRepository.cs | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/OnTopic.Data.Caching/CachedTopicRepository.cs b/OnTopic.Data.Caching/CachedTopicRepository.cs index 117d4a7b..8b2f1911 100644 --- a/OnTopic.Data.Caching/CachedTopicRepository.cs +++ b/OnTopic.Data.Caching/CachedTopicRepository.cs @@ -74,7 +74,7 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos } /*-------------------------------------------------------------------------------------------------------------------------- - | Stamp resolver on loaded graph + | Stamp resolver on seeded graph \-------------------------------------------------------------------------------------------------------------------------*/ StampResolver(_cache); @@ -256,7 +256,7 @@ public virtual void EnsureLoaded(Topic topic, TopicPayload payload) { Contract.Requires(topic); /*-------------------------------------------------------------------------------------------------------------------------- - | Filter to pending (not yet Loaded) payload + | Filter to pending (i.e. not yet Loaded) payload \-------------------------------------------------------------------------------------------------------------------------*/ payload = topic.FilterPayload(payload); @@ -421,9 +421,8 @@ protected override void OnTopicRenamed(TopicRenameEventArgs args) { | METHODS: PRIVATE \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Removes stale entries for and its descendants by swapping the - /// prefix for the current one, then re-indexes the subtree under its current unique - /// keys. + /// Removes stale _topicByKey entries for and its descendants by swapping the prefix for the current one, then reindexes the subtree under its current unique keys. /// private void RekeyTopicSubtree(Topic topic, string oldRootUniqueKey) { From 2804a557758a5dc8f5b6bdced4443d91db2c07e2 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sun, 5 Jul 2026 17:57:33 -0700 Subject: [PATCH 075/337] Remove initialization of `_topicRepository` By default, with the `CachedTopicRepository`, which is an expected implementation detail, the cache is automatically seeded with a bare root and full `Configuration` (dd0c2514). As a result, there's no need or benefit to initializing it in the (reference) `SampleActivator`. This was previously explicitly initialized for clarity since it's a shared dependency. In that way, this is more indirect. Since `CachedTopicRepository` is an expected piece of infrastructure, though, it's also redundant, so I'm removing it. This helps ensure that all consumers are using the same default sparse tree. (This can and should still be defined for cases where consumers WANT an eager-loaded, fully cached topic grpah.) --- .../SampleActivator.cs | 25 +++++++++---------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/OnTopic.AspNetCore.Mvc.Host/SampleActivator.cs b/OnTopic.AspNetCore.Mvc.Host/SampleActivator.cs index 11ca0b89..a61a0752 100644 --- a/OnTopic.AspNetCore.Mvc.Host/SampleActivator.cs +++ b/OnTopic.AspNetCore.Mvc.Host/SampleActivator.cs @@ -64,17 +64,16 @@ public SampleActivator(string connectionString) { /*-------------------------------------------------------------------------------------------------------------------------- | Initialize Topic Repository \-------------------------------------------------------------------------------------------------------------------------*/ - var sqlTopicRepository = new SqlTopicRepository(connectionString); - var cachedTopicRepository = new CachedTopicRepository(sqlTopicRepository); - _ = new PageTopicViewModel(); + var sqlTopicRepository = new SqlTopicRepository(connectionString); + var cachedTopicRepository = new CachedTopicRepository(sqlTopicRepository); + _ = new PageTopicViewModel(); /*-------------------------------------------------------------------------------------------------------------------------- | Preload repository \-------------------------------------------------------------------------------------------------------------------------*/ - _topicRepository = cachedTopicRepository; - _typeLookupService = new DynamicTopicViewModelLookupService(); - _topicMappingService = new TopicMappingService(_topicRepository, _typeLookupService); - _ = _topicRepository.Load(); + _topicRepository = cachedTopicRepository; + _typeLookupService = new DynamicTopicViewModelLookupService(); + _topicMappingService = new TopicMappingService(_topicRepository, _typeLookupService); /*-------------------------------------------------------------------------------------------------------------------------- | Establish hierarchical topic mapping service @@ -100,20 +99,20 @@ public object Create(ControllerContext context) { /*-------------------------------------------------------------------------------------------------------------------------- | Validate parameters \-------------------------------------------------------------------------------------------------------------------------*/ - Contract.Requires(context, nameof(context)); + Contract.Requires(context, nameof(context)); /*-------------------------------------------------------------------------------------------------------------------------- | Determine controller type \-------------------------------------------------------------------------------------------------------------------------*/ - var type = context.ActionDescriptor.ControllerTypeInfo.AsType(); + var type = context.ActionDescriptor.ControllerTypeInfo.AsType(); /*-------------------------------------------------------------------------------------------------------------------------- | Periodically update cache \-------------------------------------------------------------------------------------------------------------------------*/ if (DateTime.UtcNow > _cacheLastUpdated.AddMinutes(1)) { - var currentUpdate = DateTime.UtcNow; + var currentUpdate = DateTime.UtcNow; _topicRepository.Refresh(_topicRepository.Load()!, _cacheLastUpdated); - _cacheLastUpdated = currentUpdate; + _cacheLastUpdated = currentUpdate; } /*-------------------------------------------------------------------------------------------------------------------------- @@ -142,12 +141,12 @@ public object Create(ViewComponentContext context) { /*-------------------------------------------------------------------------------------------------------------------------- | Validate parameters \-------------------------------------------------------------------------------------------------------------------------*/ - Contract.Requires(context, nameof(context)); + Contract.Requires(context, nameof(context)); /*-------------------------------------------------------------------------------------------------------------------------- | Determine view component type \-------------------------------------------------------------------------------------------------------------------------*/ - var type = context.ViewComponentDescriptor.TypeInfo.AsType(); + var type = context.ViewComponentDescriptor.TypeInfo.AsType(); /*-------------------------------------------------------------------------------------------------------------------------- | Configure and return appropriate view component From 168ba8efd3ffbb893cd8ecd15dbd1f2ca85ebf44 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sun, 5 Jul 2026 18:09:57 -0700 Subject: [PATCH 076/337] Wire-up lazy-loading for `Topic.Children` When code accesses `Topic.Children` and `Topic.Children.LoadState` is `NotLoaded`, trigger the call to `ITopicLoadResolver`'s (59fa20d8) `EnsureLoad()` method (9df2db70, e25f8431). This is safe to do since we've already provided backdoor access for internal calls via a backing field (39bf06df) and guarded (the most common) potentially expensive recursive loops that would cause a cascade of database calls (110584ba, 4d83e0e1). Trigger lazy-loading of children when `NotLoaded` This completes a core promise of the lazy-loading project (#111). After this, we'll finish lazy-loading `Relationships` and `References`, which introduce their own complexity since we don't know if they or their parents are already in the graph. --- OnTopic/Topic.cs | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/OnTopic/Topic.cs b/OnTopic/Topic.cs index 9b2d9e49..e5446abd 100644 --- a/OnTopic/Topic.cs +++ b/OnTopic/Topic.cs @@ -161,7 +161,14 @@ public Topic? Parent { /// /// The children of the current . /// - public KeyedTopicCollection Children => _children; + public KeyedTopicCollection Children { + get { + if (_children.LoadState is LoadState.NotLoaded) { + _resolver?.EnsureLoaded(this, TopicPayload.Children); + } + return _children; + } + } /*============================================================================================================================ | METHOD: IS LOADED From 305c35c09d99693263823b3652c31068ddefcfb4 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sun, 5 Jul 2026 18:16:58 -0700 Subject: [PATCH 077/337] Add overload of `Load` for `TestTopicRepository` This will support additional testing of the `TopicRepository` (base class), specifically, as required for #111. This also, importantly, supports lookup by `uniqueKey`. --- .../TestDoubles/TestTopicRepository.cs | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/OnTopic.AspNetCore.Mvc.Tests/TestDoubles/TestTopicRepository.cs b/OnTopic.AspNetCore.Mvc.Tests/TestDoubles/TestTopicRepository.cs index 4f4604ec..954fac2d 100644 --- a/OnTopic.AspNetCore.Mvc.Tests/TestDoubles/TestTopicRepository.cs +++ b/OnTopic.AspNetCore.Mvc.Tests/TestDoubles/TestTopicRepository.cs @@ -6,6 +6,7 @@ using OnTopic.AspNetCore.Mvc.Controllers; using OnTopic.Attributes; using OnTopic.Internal.Diagnostics; +using OnTopic.Querying; using OnTopic.Repositories; namespace OnTopic.AspNetCore.Mvc.Tests.TestDoubles; @@ -44,6 +45,14 @@ public TestTopicRepository() : base() { /// public override Topic? Load() => _cache; + /// + public override Topic? Load( + string uniqueKey, + Topic? referenceTopic = null, + bool isRecursive = true, + TopicPayload payload = TopicPayload.All + ) => String.IsNullOrEmpty(uniqueKey)? null : _cache.FindFirst(t => t.GetUniqueKey() == uniqueKey); + /*============================================================================================================================ | METHOD: CREATE FAKE DATA \---------------------------------------------------------------------------------------------------------------------------*/ From c8bb08201acab98fdcd4d06f6be57c563f748379 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sun, 5 Jul 2026 18:31:09 -0700 Subject: [PATCH 078/337] Establish `IsLoaded()`, `EnsureLoaded()` tests This takes advantage of the new `TestTopicRepository` overload that accepts `topicId` (305c35c0) and evaluates the newly introduced functionality for `IsLoaded()` (e5ddc262), contributing to the test cases for #111. This also incorporates `EnsureLoaded()` and `SetLoadState()`. --- OnTopic.Tests/TopicRepositoryBaseTest.cs | 60 ++++++++++++++++++++++++ 1 file changed, 60 insertions(+) diff --git a/OnTopic.Tests/TopicRepositoryBaseTest.cs b/OnTopic.Tests/TopicRepositoryBaseTest.cs index f6f8a5a8..4cb94f8a 100644 --- a/OnTopic.Tests/TopicRepositoryBaseTest.cs +++ b/OnTopic.Tests/TopicRepositoryBaseTest.cs @@ -1268,6 +1268,66 @@ public void EnsureLoaded_ReferencesNotLoaded_MarksLoaded() { } + /*============================================================================================================================ + | TEST: IS LOADED: CHILDREN NOT LOADED STATE: TRIGGERS ENSURE LOADED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Loads a , marks its as , then accesses + /// the getter. Verifies that the auto-load fires, promoting the boundary to via the 's fill. + /// + [Fact] + public void IsLoaded_ChildrenNotLoadedState_TriggersEnsureLoaded() { + + var topic = _topicRepository.Load(11111); + + topic!.SetLoadState(TopicPayload.Children, LoadState.NotLoaded); + _ = topic.Children; + + Assert.True(topic.IsLoaded(TopicPayload.Children)); + + } + + /*============================================================================================================================ + | TEST: IS LOADED: CHILDREN LOADED STATE: DOES NOT CALL RESOLVER + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Loads a whose is already and accesses + /// the getter. Verifies that the boundary stays without the + /// resolver being called redundantly. + /// + [Fact] + public void IsLoaded_ChildrenLoadedState_DoesNotCallResolver() { + + var topic = _topicRepository.Load(11111); + + Assert.True(topic!.IsLoaded(TopicPayload.Children)); + _ = topic.Children; + + Assert.True(topic.IsLoaded(TopicPayload.Children)); + + } + + /*============================================================================================================================ + | TEST: IS LOADED: CHILDREN NOT LOADED: MARKS LOADED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Loads a whose has been manually set to and confirms that promotes the boundary to via the 's fill. + /// + [Fact] + public void EnsureLoaded_ChildrenNotLoaded_MarksLoaded() { + + var topic = _topicRepository.Load(11111); + + topic!.SetLoadState(TopicPayload.Children, LoadState.NotLoaded); + topic.EnsureLoaded(TopicPayload.Children); + + Assert.True(topic.IsLoaded(TopicPayload.Children)); + + } + /*============================================================================================================================ | TEST: MOVE: TOPIC MOVED EVENT: IS RAISED \---------------------------------------------------------------------------------------------------------------------------*/ From 5253452b5447719551c7dc35b5d821aa7a8bc852 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sun, 5 Jul 2026 18:47:28 -0700 Subject: [PATCH 079/337] Introducd `AssociationMap.PayloadMappings` This provides a mapping between the preexisting `CollectionType` enum and the new(er) `TopicPayload` (07a01cf8, a0071d65) flags enum. This will be used for translating `CollectionType` properties to `EnsureLoadedAsync()` requests to both ensure lazy-loading but also, more importantly, trigger those early in the chain. This is important practical plumbing to #111. --- OnTopic/Mapping/Internal/AssociationMap.cs | 26 +++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/OnTopic/Mapping/Internal/AssociationMap.cs b/OnTopic/Mapping/Internal/AssociationMap.cs index 54826e68..0d126531 100644 --- a/OnTopic/Mapping/Internal/AssociationMap.cs +++ b/OnTopic/Mapping/Internal/AssociationMap.cs @@ -4,6 +4,7 @@ | Project Topics Library \=============================================================================================================================*/ using OnTopic.Mapping.Annotations; +using OnTopic.Repositories; namespace OnTopic.Mapping.Internal; @@ -34,7 +35,19 @@ static AssociationMap() { { CollectionType.IncomingRelationship, AssociationTypes.IncomingRelationships } }; - Mappings = mappings; + // Any probes Relationships first, then Children (via NestedTopics); both must be warmed before probing + // IncomingRelationship cannot be warmed for a single topic, and MappedCollection is property-based + var payloadMappings = new Dictionary { + { CollectionType.Any, TopicPayload.Children | TopicPayload.Relationships }, + { CollectionType.Children, TopicPayload.Children }, + { CollectionType.Relationship, TopicPayload.Relationships }, + { CollectionType.NestedTopics, TopicPayload.Children }, + { CollectionType.MappedCollection, TopicPayload.None }, + { CollectionType.IncomingRelationship, TopicPayload.None } + }; + + Mappings = mappings; + PayloadMappings = payloadMappings; } @@ -43,4 +56,15 @@ static AssociationMap() { \---------------------------------------------------------------------------------------------------------------------------*/ static internal Dictionary Mappings { get; } + /*============================================================================================================================ + | PROPERTY: PAYLOAD MAPPINGS + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Provides a mapping of the relationship between and . + /// + /// + /// Used by to determine which lazy-load payloads to warm before probing collections. + /// + static internal Dictionary PayloadMappings { get; } + } //Class \ No newline at end of file From e7d8ec4bcb843bc9e499072f3e4dc51539118c3c Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sun, 5 Jul 2026 18:50:53 -0700 Subject: [PATCH 080/337] Ensure mapped collections are loaded This utilizes the new `PayloadMappings` (5b4bf6ba) to ensure that those (recognized, concrete) collections are asynchronously loaded as early in the mapping process as possible, and also at a point where we know what the `CollectionType` is known. This is a critical implementation for #111 in terms of the practical application, since most dynamic loading will be triggered via the `TopicMappingService`. --- OnTopic/Mapping/TopicMappingService.cs | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/OnTopic/Mapping/TopicMappingService.cs b/OnTopic/Mapping/TopicMappingService.cs index 4e10ec5a..2f56b62f 100644 --- a/OnTopic/Mapping/TopicMappingService.cs +++ b/OnTopic/Mapping/TopicMappingService.cs @@ -423,7 +423,7 @@ private async Task MapAsync( \-------------------------------------------------------------------------------------------------------------------------*/ async Task getList(Type targetType) { - var sourceList = GetSourceCollection(source, associations, parameter, attributePrefix); + var sourceList = await GetSourceCollectionAsync(source, associations, parameter, attributePrefix).ConfigureAwait(false); var targetList = InitializeCollection(targetType); if (sourceList is null || targetList is null) { @@ -756,7 +756,7 @@ private async Task SetCollectionValueAsync( /*-------------------------------------------------------------------------------------------------------------------------- | Establish source collection to store topics to be mapped \-------------------------------------------------------------------------------------------------------------------------*/ - var sourceList = GetSourceCollection(source, associations, memberAccessor, attributePrefix); + var sourceList = await GetSourceCollectionAsync(source, associations, memberAccessor, attributePrefix).ConfigureAwait(false); /*-------------------------------------------------------------------------------------------------------------------------- | Validate that source collection was identified @@ -788,7 +788,7 @@ private async Task SetCollectionValueAsync( /// Determines what associations the mapping should include, if any. /// The with details about the property's attributes. /// The prefix to apply to the attributes. - private IList GetSourceCollection( + private async Task> GetSourceCollectionAsync( Topic source, AssociationTypes associations, ItemMetadata itemMetadata, @@ -799,6 +799,11 @@ private IList GetSourceCollection( | Establish source collection to store topics to be mapped \-------------------------------------------------------------------------------------------------------------------------*/ var configuration = itemMetadata.Configuration; + + /*-------------------------------------------------------------------------------------------------------------------------- + | Warm lazy-loaded payload before probing collections + \-------------------------------------------------------------------------------------------------------------------------*/ + await source.EnsureLoadedAsync(AssociationMap.PayloadMappings[configuration.CollectionType]).ConfigureAwait(false); var listSource = (IList)[]; var collectionKey = configuration.CollectionKey; var collectionType = configuration.CollectionType; From fe4efe1f828dd70b591188ed61fa6694db45db9c Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sun, 5 Jul 2026 20:21:51 -0700 Subject: [PATCH 081/337] Update `.gitignore` Ignore `docs/` (which is used for Claude planning documents), `.idea` (which is used for Rider configuration), and `.DS_Store` (macOS metadata). --- .gitignore | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index c0890d77..04d69149 100644 --- a/.gitignore +++ b/.gitignore @@ -199,4 +199,7 @@ ModelManifest.xml .vs # Custom -ConnectionStrings.config \ No newline at end of file +ConnectionStrings.config +docs/ +.idea/ +*.DS_Store \ No newline at end of file From ba72f2352a0aa8b2994c86e1601834803712e454 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Mon, 6 Jul 2026 17:41:38 -0700 Subject: [PATCH 082/337] Introduced `DeferredAssociation` record Introduced a `DeferredAssociation` record in order to record associations such as Relationships or References that aren't available in the topic graph at load and, therefore, can't be fully wired up. This contributes to #111. --- OnTopic/Associations/DeferredAssociation.cs | 25 +++++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 OnTopic/Associations/DeferredAssociation.cs diff --git a/OnTopic/Associations/DeferredAssociation.cs b/OnTopic/Associations/DeferredAssociation.cs new file mode 100644 index 00000000..ab186e6b --- /dev/null +++ b/OnTopic/Associations/DeferredAssociation.cs @@ -0,0 +1,25 @@ +/*============================================================================================================================== +| Author Ignia, LLC +| Client Ignia, LLC +| Project Topics Library +\=============================================================================================================================*/ +using OnTopic.Repositories; + +namespace OnTopic.Associations; + +/*============================================================================================================================== +| RECORD: DEFERRED ASSOCIATION +\-----------------------------------------------------------------------------------------------------------------------------*/ +/// +/// Represents a deferred association between a source and a target topic that could not be resolved to an +/// in-memory instance when loaded. +/// +/// +/// This is exposed via and +/// so that the can record missing associations during a load, and then can dynamically load +/// them later when the collection is called. + +/// +/// The relationship or reference key under which the association is registered. +/// The of the target topic to be resolved. +public record DeferredAssociation(string Key, int TopicId); \ No newline at end of file From f210866efa330e90b8666fb7625df13cb627c777 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Mon, 6 Jul 2026 17:51:53 -0700 Subject: [PATCH 083/337] Added `Deferred` collections on associations Created a new `Deferred` property on both `TopicReferenceCollection` and `TopicRelationshipMultiMap`, each being a collection of the new `DeferredAssociation` record (ba72f235). This allows us to track which associations were loading with the topic but couldn't be resolved because they don't (yet) exist in the topic graph; by storing them here, we can resolve them via lazy-loading later without needing to first requery the current topic to get their relationships or references. --- OnTopic/Associations/TopicReferenceCollection.cs | 16 ++++++++++++++++ .../Associations/TopicRelationshipMultiMap.cs | 16 ++++++++++++++++ 2 files changed, 32 insertions(+) diff --git a/OnTopic/Associations/TopicReferenceCollection.cs b/OnTopic/Associations/TopicReferenceCollection.cs index aa81b5e9..c8f20105 100644 --- a/OnTopic/Associations/TopicReferenceCollection.cs +++ b/OnTopic/Associations/TopicReferenceCollection.cs @@ -3,6 +3,7 @@ | Client Ignia, LLC | Project Topics Library \=============================================================================================================================*/ +using System.Collections.ObjectModel; using OnTopic.Collections.Specialized; using OnTopic.Repositories; @@ -80,6 +81,21 @@ public bool IsFullyLoaded { set => LoadState = value? LoadState.Loaded : LoadState.NotLoaded; } + /*============================================================================================================================ + | PROPERTY: DEFERRED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Collects reference targets that were absent from the topic graph during an load, pending + /// resolution via lazy-loading. + /// + /// + /// Written to by the when a reference target cannot be found in the current . The resolves each entry + /// by calling the 's Load() method, assuming the topics haven't since been introduced + /// to the topic graph. + /// + public Collection Deferred { get; } = new(); + /*============================================================================================================================ | INSERT ITEM \---------------------------------------------------------------------------------------------------------------------------*/ diff --git a/OnTopic/Associations/TopicRelationshipMultiMap.cs b/OnTopic/Associations/TopicRelationshipMultiMap.cs index 0e1ac95d..328a14e5 100644 --- a/OnTopic/Associations/TopicRelationshipMultiMap.cs +++ b/OnTopic/Associations/TopicRelationshipMultiMap.cs @@ -3,6 +3,7 @@ | Client Ignia, LLC | Project Topics Library \=============================================================================================================================*/ +using System.Collections.ObjectModel; using OnTopic.Collections.Specialized; using OnTopic.Querying; using OnTopic.Repositories; @@ -279,6 +280,21 @@ public bool IsFullyLoaded { set => LoadState = value? LoadState.Loaded : LoadState.NotLoaded; } + /*============================================================================================================================ + | PROPERTY: DEFERRED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Collects relationship targets that were absent from the topic graph during an load, + /// pending resolution via lazy-loading. + /// + /// + /// Written to by the when a relationship target cannot be found in the current . The resolves each entry + /// by calling the 's Load() method, assuming the topics haven't since been introduced + /// to the topic graph. + /// + public Collection Deferred { get; } = new(); + /*============================================================================================================================ | METHOD: IS DIRTY? \---------------------------------------------------------------------------------------------------------------------------*/ From 55241c6bdde22ecbd6dc5351c87924f3b79b0b42 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Mon, 6 Jul 2026 22:36:17 -0700 Subject: [PATCH 084/337] Introduced new `ITopicBackingAccessor` interface This will provide the lazy-loading infrastructure (#111) a consistent way to directly access the backing fields of lazy-loaded properties without triggering the lazy-loading in the process. This has been an ongoing challenge, and this provide a cleaner solution. --- OnTopic/Repositories/ITopicBackingAccessor.cs | 67 +++++++++++++++++++ 1 file changed, 67 insertions(+) create mode 100644 OnTopic/Repositories/ITopicBackingAccessor.cs diff --git a/OnTopic/Repositories/ITopicBackingAccessor.cs b/OnTopic/Repositories/ITopicBackingAccessor.cs new file mode 100644 index 00000000..9edb1f56 --- /dev/null +++ b/OnTopic/Repositories/ITopicBackingAccessor.cs @@ -0,0 +1,67 @@ +/*============================================================================================================================== +| Author Ignia, LLC +| Client Ignia, LLC +| Project Topics Library +\=============================================================================================================================*/ +using OnTopic.Associations; +using OnTopic.Collections; + +namespace OnTopic.Repositories; + +/*============================================================================================================================== +| INTERFACE: TOPIC BACKING ACCESSOR +\-----------------------------------------------------------------------------------------------------------------------------*/ +/// +/// Provides direct access to the backing fields of a , bypassing the autoloading property getters. +/// +/// +/// +/// exposes , , and as autoloading getters: Accessing them can trigger a synchronous call. Repository and resolver infrastructure that reads or +/// writes these collections as part of a load or resolve operation must bypass those getters to avoid infinite loops. +/// +/// +/// implements this interface via explicit interface implementations. Callers must cast to to access the raw backing fields. +/// +/// +public interface ITopicBackingAccessor { + + /*============================================================================================================================ + | PROPERTY: CHILDREN + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Returns the raw backing field, bypassing the autoloading getter. + /// + /// + /// This is to be applied as explicit interface implementations; callers must cast to to + /// access this member. + /// + KeyedTopicCollection Children { get; } + + /*============================================================================================================================ + | PROPERTY: RELATIONSHIPS + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Returns the raw backing field, bypassing the autoloading getter. + /// + /// + /// This is to be applied as explicit interface implementations; callers must cast to to + /// access this member. + /// + TopicRelationshipMultiMap Relationships { get; } + + /*============================================================================================================================ + | PROPERTY: REFERENCES + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Returns the raw backing field, bypassing the autoloading getter. + /// + /// + /// This is to be applied as explicit interface implementations; callers must cast to to + /// access this member. + /// + TopicReferenceCollection References { get; } + +} //Interface \ No newline at end of file From a9035bb8c12975d05794b98ef0cace22106dee46 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Mon, 6 Jul 2026 22:39:25 -0700 Subject: [PATCH 085/337] Implemented `ITopicBackingAccessor` on `Topic` This implements the new `ITopicBackingAccessor` interface (55241c6b) on the `Topic` entity as explicit interface implementations, thus allowing the lazy-loading infrastructure (#111) to case `Topic` as `ITopicBackingAccessor` in order to get direct access to the backing fields of lazy-loaded properties without (re)triggering lazy loading. As part of this, I established a new `#region` for the Lazy-Load Infrastructure to aid with cold folding. --- OnTopic/Topic.cs | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/OnTopic/Topic.cs b/OnTopic/Topic.cs index e5446abd..978c2629 100644 --- a/OnTopic/Topic.cs +++ b/OnTopic/Topic.cs @@ -608,6 +608,24 @@ public DateTime LastModified { set => SetAttributeValue("LastModified", value.ToString(CultureInfo.InvariantCulture)); } + #endregion + + #region Lazy-Loading Infrastructure + + /*============================================================================================================================ + | INTERFACE: TOPIC BACKING ACCESSOR + \---------------------------------------------------------------------------------------------------------------------------*/ + + /// + KeyedTopicCollection ITopicBackingAccessor.Children => _children; + + /// + TopicRelationshipMultiMap ITopicBackingAccessor.Relationships => _relationships; + + /// + TopicReferenceCollection ITopicBackingAccessor.References => _references; + + #endregion #region Relationship and Collection Methods From 819e3735085878e9529b1c189a630668452ca6ea Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 7 Jul 2026 00:08:53 -0700 Subject: [PATCH 086/337] Change `_resolver` to a `Resolver` property Since `_resolver` is `internal` and used by the lazy-loading infrastructure (#111) outside of `Topic`, it should be a property, not a field, following the standard conventions. As part of this, I also moved it down to the newly established `#region` for the lazy-loading infrastructure (a9035bb8). --- OnTopic.Tests/TopicRepositoryBaseTest.cs | 2 +- OnTopic.Tests/TopicTest.cs | 2 +- .../Repositories/ObservableTopicRepository.cs | 4 ++-- OnTopic/Topic.cs | 20 +++++++++++++------ 4 files changed, 18 insertions(+), 10 deletions(-) diff --git a/OnTopic.Tests/TopicRepositoryBaseTest.cs b/OnTopic.Tests/TopicRepositoryBaseTest.cs index 4cb94f8a..53d60c18 100644 --- a/OnTopic.Tests/TopicRepositoryBaseTest.cs +++ b/OnTopic.Tests/TopicRepositoryBaseTest.cs @@ -1150,7 +1150,7 @@ public void Save_NewTopic_StampsResolver() { _topicRepository.Save(topic); - Assert.NotNull(topic._resolver); + Assert.NotNull(topic.Resolver); } diff --git a/OnTopic.Tests/TopicTest.cs b/OnTopic.Tests/TopicTest.cs index 37bd2636..5b393d7d 100644 --- a/OnTopic.Tests/TopicTest.cs +++ b/OnTopic.Tests/TopicTest.cs @@ -565,7 +565,7 @@ public void EnsureLoaded_IsNew_DoesNotInvokeResolver() { | Establish tracking resolver \-------------------------------------------------------------------------------------------------------------------------*/ var tracker = new TrackingTopicLoadResolver(); - topic._resolver = tracker; + topic.Resolver = tracker; topic.Children.LoadState = LoadState.NotLoaded; /*-------------------------------------------------------------------------------------------------------------------------- diff --git a/OnTopic/Repositories/ObservableTopicRepository.cs b/OnTopic/Repositories/ObservableTopicRepository.cs index 096fd6c8..a44125b7 100644 --- a/OnTopic/Repositories/ObservableTopicRepository.cs +++ b/OnTopic/Repositories/ObservableTopicRepository.cs @@ -286,7 +286,7 @@ public event EventHandler? TopicRenamed { /// not itself a resolver leaves any existing inner stamp intact, rather than overwriting it. /// /// - /// Recursion is gated on so that unloaded branches are not force-loaded. + /// Recursion is gated on so that unloaded branches are not force-loaded. /// /// /// Call this method once on the root of a loaded or saved graph; it stamps every resident node in one pass. @@ -301,7 +301,7 @@ protected void StampResolver(Topic? topic) { } // Stamp the resolver on the topic - topic._resolver = resolver; + topic.Resolver = resolver; // If the children aren't yet loaded, don't bother with them yet if (!topic.IsLoaded(TopicPayload.Children)) { diff --git a/OnTopic/Topic.cs b/OnTopic/Topic.cs index 978c2629..ab5fad83 100644 --- a/OnTopic/Topic.cs +++ b/OnTopic/Topic.cs @@ -32,7 +32,6 @@ public class Topic: ITrackDirtyKeys { private Topic? _parent; private readonly KeyedTopicCollection _children = new(); readonly DirtyKeyCollection _dirtyKeys = new(); - internal ITopicLoadResolver? _resolver; /*============================================================================================================================ | CONSTRUCTOR @@ -164,7 +163,7 @@ public Topic? Parent { public KeyedTopicCollection Children { get { if (_children.LoadState is LoadState.NotLoaded) { - _resolver?.EnsureLoaded(this, TopicPayload.Children); + Resolver?.EnsureLoaded(this, TopicPayload.Children); } return _children; } @@ -295,7 +294,7 @@ public void EnsureLoaded(TopicPayload payload) { /*-------------------------------------------------------------------------------------------------------------------------- | Skip for obvious reasons \-------------------------------------------------------------------------------------------------------------------------*/ - if (_resolver is null || IsNew) { + if (Resolver is null || IsNew) { return; } @@ -309,7 +308,7 @@ public void EnsureLoaded(TopicPayload payload) { } // Ensure the appropriate payload are loaded - _resolver.EnsureLoaded(this, payload); + Resolver.EnsureLoaded(this, payload); } @@ -323,7 +322,7 @@ public Task EnsureLoadedAsync(TopicPayload payload, CancellationToken cancellati /*-------------------------------------------------------------------------------------------------------------------------- | Skip for obvious reasons \-------------------------------------------------------------------------------------------------------------------------*/ - if (_resolver is null || IsNew) { + if (Resolver is null || IsNew) { return Task.CompletedTask; } @@ -337,7 +336,7 @@ public Task EnsureLoadedAsync(TopicPayload payload, CancellationToken cancellati } // Ensure the appropriate payload are loaded - return _resolver.EnsureLoadedAsync(this, payload, cancellationToken); + return Resolver.EnsureLoadedAsync(this, payload, cancellationToken); } @@ -612,6 +611,15 @@ public DateTime LastModified { #region Lazy-Loading Infrastructure + /*============================================================================================================================ + | PROPERTY: RESOLVER + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Provides an internal reference to the used to lazy load collections on request. This is + /// applied via the method. + /// + internal ITopicLoadResolver? Resolver { get; set; } + /*============================================================================================================================ | INTERFACE: TOPIC BACKING ACCESSOR \---------------------------------------------------------------------------------------------------------------------------*/ From 57457664ab9461989cf3630aa99ae24c7fc472fd Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 7 Jul 2026 00:09:43 -0700 Subject: [PATCH 087/337] Fixed XML docblock --- OnTopic.TestDoubles/StubTopicRepository.cs | 1 - 1 file changed, 1 deletion(-) diff --git a/OnTopic.TestDoubles/StubTopicRepository.cs b/OnTopic.TestDoubles/StubTopicRepository.cs index d699193af..3ad3d9cb 100644 --- a/OnTopic.TestDoubles/StubTopicRepository.cs +++ b/OnTopic.TestDoubles/StubTopicRepository.cs @@ -207,7 +207,6 @@ protected override void SaveTopic([NotNull]Topic topic, DateTime version, bool p /// without merging real blob data, allowing tests to exercise the fill path without a live /// database. /// - /// public virtual void EnsureLoaded(Topic topic, TopicPayload payload) { /*-------------------------------------------------------------------------------------------------------------------------- From 17bd6263d7e7acff1629a4873479a7deadf0aff7 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 7 Jul 2026 00:10:21 -0700 Subject: [PATCH 088/337] Fixed alignment in `TrackingTopicLoadResolver` --- OnTopic.Tests/TestDoubles/TrackingTopicLoadResolver.cs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/OnTopic.Tests/TestDoubles/TrackingTopicLoadResolver.cs b/OnTopic.Tests/TestDoubles/TrackingTopicLoadResolver.cs index 2c48445f..4ebb07ff 100644 --- a/OnTopic.Tests/TestDoubles/TrackingTopicLoadResolver.cs +++ b/OnTopic.Tests/TestDoubles/TrackingTopicLoadResolver.cs @@ -23,7 +23,7 @@ internal sealed class TrackingTopicLoadResolver : ITopicLoadResolver { /// Returns if either or was invoked. /// - public bool WasCalled { get; private set; } + public bool WasCalled { get; private set; } /*============================================================================================================================ | METHOD: ENSURE LOADED @@ -40,8 +40,8 @@ Task ITopicLoadResolver.EnsureLoadedAsync( TopicPayload payload, CancellationToken cancellationToken ) { - WasCalled = true; + WasCalled = true; return Task.CompletedTask; } -} //Class +} //Class \ No newline at end of file From 520ce3c510e5ea5c6515170377dd9240f141dc73 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 7 Jul 2026 00:28:24 -0700 Subject: [PATCH 089/337] Remove `Deferred` items when associations added When a `TopicReferenceRecord` is is added to `TopicReferenceCollection` or a `Topic` is added to `TopicRelationshipMultiMap`, we know that item should no longer be in the `Deferred` collection (f210866e) and can automatically remove it. This eliminates the need for the lazy-loading infrastructure (#111) to manually maintain this list, making it just a consumer. --- .../Associations/TopicReferenceCollection.cs | 20 +++++++++++++++++++ .../Associations/TopicRelationshipMultiMap.cs | 8 ++++++++ 2 files changed, 28 insertions(+) diff --git a/OnTopic/Associations/TopicReferenceCollection.cs b/OnTopic/Associations/TopicReferenceCollection.cs index c8f20105..456fd90d 100644 --- a/OnTopic/Associations/TopicReferenceCollection.cs +++ b/OnTopic/Associations/TopicReferenceCollection.cs @@ -112,6 +112,16 @@ protected override void InsertItem(int index, TopicReferenceRecord item) { \-------------------------------------------------------------------------------------------------------------------------*/ base.InsertItem(index, item); + /*-------------------------------------------------------------------------------------------------------------------------- + | Remove any pending deferred entry for this reference key + \-------------------------------------------------------------------------------------------------------------------------*/ + for (var i = Deferred.Count - 1; i >= 0; i--) { + if (Deferred[i].Key == item.Key) { + Deferred.RemoveAt(i); + break; + } + } + /*-------------------------------------------------------------------------------------------------------------------------- | Handle recipricol references \-------------------------------------------------------------------------------------------------------------------------*/ @@ -140,6 +150,16 @@ protected override void SetItem(int index, TopicReferenceRecord item) { \-------------------------------------------------------------------------------------------------------------------------*/ base.SetItem(index, item); + /*-------------------------------------------------------------------------------------------------------------------------- + | Remove any pending deferred entry for this reference key + \-------------------------------------------------------------------------------------------------------------------------*/ + for (var i = Deferred.Count - 1; i >= 0; i--) { + if (Deferred[i].Key == item.Key) { + Deferred.RemoveAt(i); + break; + } + } + /*-------------------------------------------------------------------------------------------------------------------------- | Handle recipricol references \-------------------------------------------------------------------------------------------------------------------------*/ diff --git a/OnTopic/Associations/TopicRelationshipMultiMap.cs b/OnTopic/Associations/TopicRelationshipMultiMap.cs index 328a14e5..7d042ffc 100644 --- a/OnTopic/Associations/TopicRelationshipMultiMap.cs +++ b/OnTopic/Associations/TopicRelationshipMultiMap.cs @@ -211,6 +211,14 @@ internal void SetValue(string relationshipKey, Topic topic, bool? markDirty, boo else { _dirtyKeys.MarkDirty(relationshipKey); } + + // Remove any pending deferred entry for this relationship/target pair + for (var i = Deferred.Count - 1; i >= 0; i--) { + if (Deferred[i].Key == relationshipKey && Deferred[i].TopicId == topic.Id) { + Deferred.RemoveAt(i); + break; + } + } } /*-------------------------------------------------------------------------------------------------------------------------- From 3c278130ab9455b315bd0e171a8fe5c1d4855955 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 7 Jul 2026 00:39:44 -0700 Subject: [PATCH 090/337] Always return associations with `Load()` With the `Deferred` collections in place on `Topic.Relationships` and `Topic.References` (f210866e), we should _always_ call the `GetTopics` stored procedure with the`@IncludeRelationships` and `@IncludeReferences` parameters (8c2c81da) when using `Load()` because a) these are relatively cheap (just a list of strings and ints), and b) this saves us from having to requery them later when dynamically loading (#111) relationships and references. This also means this isn't needed for `EnsureLoaded()`, since we know these will always be available in the `Deferred` collection. --- OnTopic.Data.Sql/SqlTopicRepository.cs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index 8a3bb04b..9a239100 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -145,6 +145,8 @@ public override Topic Load( command.AddParameter("LoadDescendants", isRecursive); command.AddParameter("LoadAscendants", topicId >= 0 && referenceTopic is null); command.AddParameter("IncludeExtended", payload.HasFlag(TopicPayload.ExtendedAttributes)); + command.AddParameter("IncludeRelationships", true); + command.AddParameter("IncludeReferences", true); /*-------------------------------------------------------------------------------------------------------------------------- | Process database query From fce368be88908fc5885f091f91c9f19a63e477bc Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 7 Jul 2026 01:28:01 -0700 Subject: [PATCH 091/337] Add missing associations to `Deferred` When `SetRelationships()` or `SetReferences()` can't find the target topic within the topic graph (via the topic index), that target topic's ID should be added to the new `Deferred` collection (f210866e). This mirrors the automatic remove from `Deferred` when a topic is added (520ce3c5). This contributes to #111. --- OnTopic.Data.Sql/SqlDataReaderExtensions.cs | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs index 1e99035e..70afbf5a 100644 --- a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs +++ b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs @@ -5,6 +5,7 @@ \=============================================================================================================================*/ using System.Diagnostics; using System.Net; +using OnTopic.Associations; using OnTopic.Collections.Specialized; using OnTopic.Querying; using OnTopic.Repositories; @@ -466,9 +467,9 @@ internal static void SetRelationships(this IDataReader reader, TopicIndex topics related = relatedTopic; } - // Bypass if the target object is missing + // When the target is absent, defer it for resolution on next access if (related is null) { - current.Relationships.LoadState = LoadState.NotLoaded; + current.Relationships.Deferred.Add(new(relationshipKey, targetTopicId)); return; } @@ -517,14 +518,18 @@ internal static void SetReferences(this IDataReader reader, TopicIndex topics, b var current = topics[sourceTopicId]; var referenced = (Topic?)null; - // Fetch the related topic - if (targetTopicId is null) { + // This happens when the reference has been deleted, so SetValue() will remove the reference + if (targetTopicId is null) { } + + // Attempt to get a reference to the target via the topic index else if (topics.TryGetValue(targetTopicId.Value, out var referencedTopic)) { referenced = referencedTopic; } + + // When the target isn't (yet) available, defer it to be lazy loaded when the references are accessed else { - current.References.LoadState = LoadState.NotLoaded; + current.References.Deferred.Add(new(referenceKey, targetTopicId.Value)); return; } From c65307f525f5c73debf87f00c439638f18a39896 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 7 Jul 2026 01:55:13 -0700 Subject: [PATCH 092/337] Dynamically maintain `LoadState` using `Deferred` With `Topic.Relationships` and `Topic.References` now always being loaded (3c278130), and any missing associations automatically being added (fce368be) to the `Deferred` collections (f210866e), we can just rely on the `Deferred` count for defining the value of `LoadState`, instead of needing to manually manage that via `SetLoadState()`. This contributes to the lazy-loading project (#111). As part of this, I also removed the now unused `IsFullyLoaded` properties, which `LoadState` replaced (486f963c). --- OnTopic.Data.Sql/SqlTopicRepository.cs | 4 --- OnTopic.Tests/TopicRepositoryBaseTest.cs | 5 +-- .../Associations/TopicReferenceCollection.cs | 34 +++---------------- .../Associations/TopicRelationshipMultiMap.cs | 34 +++---------------- OnTopic/Topic.cs | 10 ------ 5 files changed, 11 insertions(+), 76 deletions(-) diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index 9a239100..5b423f9e 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -277,10 +277,6 @@ public override Topic Load(int topicId, DateTime version, Topic? referenceTopic | Catch exception \-------------------------------------------------------------------------------------------------------------------------*/ catch (SqlException exception) { - if (topic is not null) { - topic.Relationships.LoadState = LoadState.NotLoaded; - topic.References.LoadState = LoadState.NotLoaded; - } throw new TopicRepositoryException($"Topics failed to load: '{exception.Message}'", exception); } diff --git a/OnTopic.Tests/TopicRepositoryBaseTest.cs b/OnTopic.Tests/TopicRepositoryBaseTest.cs index 53d60c18..3f17a874 100644 --- a/OnTopic.Tests/TopicRepositoryBaseTest.cs +++ b/OnTopic.Tests/TopicRepositoryBaseTest.cs @@ -3,6 +3,7 @@ | Client Ignia, LLC | Project Topics Library \=============================================================================================================================*/ +using OnTopic.Associations; using OnTopic.Collections.Specialized; using OnTopic.Data.Caching; using OnTopic.Metadata; @@ -1236,7 +1237,7 @@ public void EnsureLoaded_RelationshipsNotLoaded_MarksLoaded() { var topic = _topicRepository.Load(11111); - topic!.Relationships.LoadState = LoadState.NotLoaded; + topic!.Relationships.Deferred.Add(new("_stub", 11111)); topic.EnsureLoaded(TopicPayload.Relationships); Assert.True(topic.IsLoaded(TopicPayload.Relationships)); @@ -1261,7 +1262,7 @@ public void EnsureLoaded_ReferencesNotLoaded_MarksLoaded() { var topic = _topicRepository.Load(11111); - topic!.References.LoadState = LoadState.NotLoaded; + topic!.References.Deferred.Add(new("_stub", 11111)); topic.EnsureLoaded(TopicPayload.References); Assert.True(topic.IsLoaded(TopicPayload.References)); diff --git a/OnTopic/Associations/TopicReferenceCollection.cs b/OnTopic/Associations/TopicReferenceCollection.cs index 456fd90d..7ebf3612 100644 --- a/OnTopic/Associations/TopicReferenceCollection.cs +++ b/OnTopic/Associations/TopicReferenceCollection.cs @@ -48,38 +48,12 @@ public TopicReferenceCollection(Topic parentTopic) : base(parentTopic) { } /// allowing callers to distinguish data that is present and authoritative from data that must still be fetched. /// /// - /// Defaults to . The repository sets this to when any - /// referenced topic cannot be resolved to an in-memory instance during load. The persistence store may optionally - /// provide an indicator of the count without returning the full data, thus allowing this to be set to if, in fact, there are no topic references. While in that state, the + /// Returns when contains values, meaning one or more references + /// aren't yet available and must be lazy loaded. Returns once is + /// empty, meaning all targets have been loaded. While , the /// will not delete unmatched references on save, preventing unintended data loss. /// - public LoadState LoadState { get; set; } = LoadState.Loaded; - - /*============================================================================================================================ - | IS FULLY LOADED? - \---------------------------------------------------------------------------------------------------------------------------*/ - /// - /// Determines whether or not the collection was fully loaded from the persistence store. - /// - /// - /// - /// When loading an individual or branch from the persistence store, it is possible that topic - /// references may not be fully available. In this scenario, updating topic references while e.g. deleting unmatched - /// relationships can result in unintended data loss. To account for this, the property ' - /// tracks whether a collection was fully loaded from the persistence store; if it wasn't, the should not deleted unmatched topic references. - /// - /// - /// The property defaults to true. It should be set to false during the method if any members of the collection cannot - /// be mapped back to a valid reference in memory. - /// - /// - public bool IsFullyLoaded { - get => LoadState is LoadState.Loaded; - set => LoadState = value? LoadState.Loaded : LoadState.NotLoaded; - } + public LoadState LoadState => Deferred.Count > 0 ? LoadState.NotLoaded : LoadState.Loaded; /*============================================================================================================================ | PROPERTY: DEFERRED diff --git a/OnTopic/Associations/TopicRelationshipMultiMap.cs b/OnTopic/Associations/TopicRelationshipMultiMap.cs index 7d042ffc..79bd73d5 100644 --- a/OnTopic/Associations/TopicRelationshipMultiMap.cs +++ b/OnTopic/Associations/TopicRelationshipMultiMap.cs @@ -255,38 +255,12 @@ public void SetTopic(string relationshipKey, Topic topic, bool? isDirty, bool is /// allowing callers to distinguish data that is present and authoritative from data that must still be fetched. /// /// - /// Defaults to . The repository conditionally sets this to - /// when any related topic cannot be resolved to an in-memory instance during load. The persistence store may optionally - /// provide an indicator of the count without returning the full data, thus allowing this to be set to if, in fact, there are no related topics. While in that state, the + /// Returns when contains values, meaning one or more relationships + /// aren't yet available and must be lazy loaded. Returns once is + /// empty, meaning all targets have been loaded. While , the /// will not delete unmatched relationships on save, preventing unintended data loss. /// - public LoadState LoadState { get; set; } = LoadState.Loaded; - - /*============================================================================================================================ - | IS FULLY LOADED? - \---------------------------------------------------------------------------------------------------------------------------*/ - /// - /// Determines whether or not the collection was fully loaded from the persistence store. - /// - /// - /// - /// When loading an individual or branch from the persistence store, it is possible that the - /// relationships may not be fully available. In this scenario, updating relationships while e.g. deleting unmatched - /// relationships can result in unintended data loss. To account for this, the property - /// tracks whether a collection was fully loaded from the persistence store; if it wasn't, the should not deleted unmatched relationships. - /// - /// - /// The property defaults to true. It should be set to false during the method if any members of the collection cannot be mapped - /// back to a valid reference in memory. - /// - /// - public bool IsFullyLoaded { - get => LoadState is LoadState.Loaded; - set => LoadState = value? LoadState.Loaded : LoadState.NotLoaded; - } + public LoadState LoadState => Deferred.Count > 0 ? LoadState.NotLoaded : LoadState.Loaded; /*============================================================================================================================ | PROPERTY: DEFERRED diff --git a/OnTopic/Topic.cs b/OnTopic/Topic.cs index ab5fad83..685ab6bd 100644 --- a/OnTopic/Topic.cs +++ b/OnTopic/Topic.cs @@ -235,16 +235,6 @@ public void SetLoadState(TopicPayload payload, LoadState state) { Attributes.LoadState = state; } - // Relationships - if (payload.HasFlag(TopicPayload.Relationships)) { - Relationships.LoadState = state; - } - - // References - if (payload.HasFlag(TopicPayload.References)) { - References.LoadState = state; - } - } /*============================================================================================================================ From e1b28c739b696443b192cedc6ae1d2882d02804b Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 7 Jul 2026 01:58:09 -0700 Subject: [PATCH 093/337] Implemented backing fields for associations This was missed when implementing the `ITopicBackingAccessor` on `Topic`, even though the explicit interface implementations called them (a9035bb8). I also neglected to add the `ITopicBackingAccessor` itself to `Topic`. Whoops! This contributes to #111. --- OnTopic/Topic.cs | 40 +++++++++++++++++++++++++--------------- 1 file changed, 25 insertions(+), 15 deletions(-) diff --git a/OnTopic/Topic.cs b/OnTopic/Topic.cs index 685ab6bd..9e6fc691 100644 --- a/OnTopic/Topic.cs +++ b/OnTopic/Topic.cs @@ -21,7 +21,7 @@ namespace OnTopic; /// The Topic object is a simple container for a particular node in the topic hierarchy. It contains the metadata associated /// with the particular node, a list of children, etc. /// -public class Topic: ITrackDirtyKeys { +public class Topic: ITrackDirtyKeys, ITopicBackingAccessor { /*============================================================================================================================ | PRIVATE VARIABLES @@ -31,6 +31,8 @@ public class Topic: ITrackDirtyKeys { private string? _originalKey; private Topic? _parent; private readonly KeyedTopicCollection _children = new(); + private readonly TopicRelationshipMultiMap _relationships; + private readonly TopicReferenceCollection _references; readonly DirtyKeyCollection _dirtyKeys = new(); /*============================================================================================================================ @@ -62,8 +64,8 @@ public Topic(string key, string contentType, Topic? parent = null, int id = -1) \-------------------------------------------------------------------------------------------------------------------------*/ Attributes = new(this); IncomingRelationships = new(this, true); - Relationships = new(this, false); - References = new(this); + _relationships = new(this, false); + _references = new(this); VersionHistory = new(); /*-------------------------------------------------------------------------------------------------------------------------- @@ -194,12 +196,12 @@ public bool IsLoaded(TopicPayload payload) { } // Relationships - if (payload.HasFlag(TopicPayload.Relationships) && Relationships.LoadState is not LoadState.Loaded) { + if (payload.HasFlag(TopicPayload.Relationships) && _relationships.LoadState is not LoadState.Loaded) { return false; } // References - if (payload.HasFlag(TopicPayload.References) && References.LoadState is not LoadState.Loaded) { + if (payload.HasFlag(TopicPayload.References) && _references.LoadState is not LoadState.Loaded) { return false; } @@ -775,8 +777,8 @@ public bool IsDirty(bool checkCollections, bool excludeLastModified = false) { } else if ( Attributes.IsDirty(excludeLastModified) || - Relationships.IsDirty() || - References.IsDirty() + _relationships.IsDirty() || + _references.IsDirty() ) { return true; } @@ -797,8 +799,8 @@ public bool IsDirty(string key, bool checkCollections) { } else if ( Attributes.IsDirty(key) || - Relationships.IsDirty(key) || - References.IsDirty(key) + _relationships.IsDirty(key) || + _references.IsDirty(key) ) { return true; } @@ -830,8 +832,8 @@ public void MarkClean(bool includeCollections, DateTime? version = null) { _dirtyKeys.MarkClean(); if (includeCollections) { Attributes.MarkClean(version); - Relationships.MarkClean(); - References.MarkClean(); + _relationships.MarkClean(); + _references.MarkClean(); } } @@ -851,8 +853,8 @@ public void MarkClean(string key, bool includeCollections) { _dirtyKeys.MarkClean(key); if (includeCollections) { Attributes.MarkClean(key); - Relationships.MarkClean(key); - References.MarkClean(key); + _relationships.MarkClean(key); + _references.MarkClean(key); } } @@ -946,7 +948,11 @@ public Topic? DerivedTopic { /// topic, thus allowing the topic hierarchy to be represented as a network graph. /// /// The current 's relationships. - public TopicRelationshipMultiMap Relationships { get; } + public TopicRelationshipMultiMap Relationships { + get { + return _relationships; + } + } /*============================================================================================================================ | PROPERTY: REFERENCES @@ -959,7 +965,11 @@ public Topic? DerivedTopic { /// BaseTopic for a ). /// /// The current 's references. - public TopicReferenceCollection References { get; } + public TopicReferenceCollection References { + get { + return _references; + } + } /*============================================================================================================================ | PROPERTY: INCOMING RELATIONSHIPS From d08141324353048e63bc33ff6c5ad677f97fa004 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 7 Jul 2026 02:25:39 -0700 Subject: [PATCH 094/337] Added `Attributes` to `ITopicBackingAccessor` When I originally introduced (55241c6b) and implemented (a9035bb8) `ITopicBackingAccessor`, I hadn't included `Attributes` because a) it doesn't have a backing field, and b) it doesn't trigger lazy-loading based on access to the `Attributes` property. But this is inconsistent, leaks internal implementation details to understand, and fails to insulate us in case we decide to change how attributes are lazy-loaded in the future. Based on that, I've retrofitted `ITopicBackingAccessor` with `Attributes`, and added the explicit interface implementation for it to `Topic`. --- OnTopic/Repositories/ITopicBackingAccessor.cs | 13 +++++++++++++ OnTopic/Topic.cs | 2 ++ 2 files changed, 15 insertions(+) diff --git a/OnTopic/Repositories/ITopicBackingAccessor.cs b/OnTopic/Repositories/ITopicBackingAccessor.cs index 9edb1f56..8de29d82 100644 --- a/OnTopic/Repositories/ITopicBackingAccessor.cs +++ b/OnTopic/Repositories/ITopicBackingAccessor.cs @@ -4,6 +4,7 @@ | Project Topics Library \=============================================================================================================================*/ using OnTopic.Associations; +using OnTopic.Attributes; using OnTopic.Collections; namespace OnTopic.Repositories; @@ -64,4 +65,16 @@ public interface ITopicBackingAccessor { /// TopicReferenceCollection References { get; } + /*============================================================================================================================ + | PROPERTY: ATTRIBUTES + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Returns the raw backing field, bypassing the autoloading getter. + /// + /// + /// This is to be applied as explicit interface implementations; callers must cast to to + /// access this member. + /// + AttributeCollection Attributes { get; } + } //Interface \ No newline at end of file diff --git a/OnTopic/Topic.cs b/OnTopic/Topic.cs index 9e6fc691..88218913 100644 --- a/OnTopic/Topic.cs +++ b/OnTopic/Topic.cs @@ -625,6 +625,8 @@ public DateTime LastModified { /// TopicReferenceCollection ITopicBackingAccessor.References => _references; + /// + AttributeCollection ITopicBackingAccessor.Attributes => Attributes; #endregion From 2c4e23d02fe1fef902a6a9b1c81d4ac9736b20f2 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 7 Jul 2026 14:33:11 -0700 Subject: [PATCH 095/337] Ensured access through `ITopicBackingAccessor` Throughout the lazy-loading infrastructure (#111), I ensured that access to the lazy-loaded properties on the `Topic` object are accessed through `ITopicBackingAccessor` (55241c6b, 819e3735) to ensure that they don't trip a loop on triggering the lazy-loading contract they're attempting to fulfill. As part of this, I established the convention of calling this `rawTopic`. There were several places where this was the only topic reference needed, and I could have changed the signature, but I kept the boxing from `topic` to `rawTopic` and variable name to reinforce that this is going through the backing fields. --- OnTopic.Data.Sql/SqlDataReaderExtensions.cs | 33 +++++++++++++-------- OnTopic.Data.Sql/SqlTopicRepository.cs | 31 +++++++++++-------- 2 files changed, 39 insertions(+), 25 deletions(-) diff --git a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs index 70afbf5a..5f45aa5c 100644 --- a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs +++ b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs @@ -5,7 +5,6 @@ \=============================================================================================================================*/ using System.Diagnostics; using System.Net; -using OnTopic.Associations; using OnTopic.Collections.Specialized; using OnTopic.Querying; using OnTopic.Repositories; @@ -87,10 +86,12 @@ internal static class SqlDataReaderExtensions { // The first topic returned is the root topic; store it for the return value rootTopic ??= addedTopic; + var rawTopic = (ITopicBackingAccessor)addedTopic; + // HasExtendedAttribute is NULL when extended attributes are included // HasExtendedAttribute is true when the blob wasn't loaded, but exists if (reader.GetNullableBoolean("HasExtendedAttributes") is true) { - addedTopic.Attributes.LoadState = LoadState.NotLoaded; + rawTopic.Attributes.LoadState = LoadState.NotLoaded; } // HasChildren is NULL when the column is not applicable (e.g., in version or update paths); skip those topics. @@ -333,11 +334,12 @@ internal static void SetIndexedAttributes(this IDataReader reader, TopicIndex to | Identify topic \-------------------------------------------------------------------------------------------------------------------------*/ var current = topics[topicId]; + var rawTopic = (ITopicBackingAccessor)current; /*-------------------------------------------------------------------------------------------------------------------------- | Set attribute value \-------------------------------------------------------------------------------------------------------------------------*/ - current.Attributes.SetValue(attributeKey, attributeValue, markDirty, version, false); + rawTopic.Attributes.SetValue(attributeKey, attributeValue, markDirty, version, false); } @@ -388,6 +390,7 @@ internal static void SetExtendedAttributes( | Identify the current topic \-------------------------------------------------------------------------------------------------------------------------*/ var current = topics[topicId]; + var rawTopic = (ITopicBackingAccessor)current; /*-------------------------------------------------------------------------------------------------------------------------- | Handle scenario where there isn't an element @@ -420,9 +423,9 @@ internal static void SetExtendedAttributes( if (String.IsNullOrEmpty(attributeValue)) continue; // Skip keys already dirty in memory to avoid clobbering unsaved values during a lazy fill - if (preserveDirty && current.Attributes.IsDirty(attributeKey)) continue; + if (preserveDirty && rawTopic.Attributes.IsDirty(attributeKey)) continue; - current.Attributes.SetValue(attributeKey, attributeValue, markDirty, version, true); + rawTopic.Attributes.SetValue(attributeKey, attributeValue, markDirty, version, true); } while (xmlReader.Name is "attribute"); @@ -460,6 +463,7 @@ internal static void SetRelationships(this IDataReader reader, TopicIndex topics | Identify affected topics \-------------------------------------------------------------------------------------------------------------------------*/ var current = topics[sourceTopicId]; + var rawTopic = (ITopicBackingAccessor)current; var related = (Topic?)null; // Fetch the related topic @@ -469,7 +473,7 @@ internal static void SetRelationships(this IDataReader reader, TopicIndex topics // When the target is absent, defer it for resolution on next access if (related is null) { - current.Relationships.Deferred.Add(new(relationshipKey, targetTopicId)); + rawTopic.Relationships.Deferred.Add(new(relationshipKey, targetTopicId)); return; } @@ -477,10 +481,10 @@ internal static void SetRelationships(this IDataReader reader, TopicIndex topics | Set relationship on object \-------------------------------------------------------------------------------------------------------------------------*/ if (!isDeleted) { - current.Relationships.SetValue(relationshipKey, related, markDirty); + rawTopic.Relationships.SetValue(relationshipKey, related, markDirty); } - else if (current.Relationships.Contains(relationshipKey, related)) { - current.Relationships.Remove(relationshipKey, related); + else if (rawTopic.Relationships.Contains(relationshipKey, related)) { + rawTopic.Relationships.Remove(relationshipKey, related); } } @@ -516,6 +520,7 @@ internal static void SetReferences(this IDataReader reader, TopicIndex topics, b | Identify affected topics \-------------------------------------------------------------------------------------------------------------------------*/ var current = topics[sourceTopicId]; + var rawTopic = (ITopicBackingAccessor)current; var referenced = (Topic?)null; // This happens when the reference has been deleted, so SetValue() will remove the reference @@ -529,14 +534,14 @@ internal static void SetReferences(this IDataReader reader, TopicIndex topics, b // When the target isn't (yet) available, defer it to be lazy loaded when the references are accessed else { - current.References.Deferred.Add(new(referenceKey, targetTopicId.Value)); + rawTopic.References.Deferred.Add(new(referenceKey, targetTopicId.Value)); return; } /*-------------------------------------------------------------------------------------------------------------------------- | Set reference on object \-------------------------------------------------------------------------------------------------------------------------*/ - current.References.SetValue(referenceKey, referenced, markDirty); + rawTopic.References.SetValue(referenceKey, referenced, markDirty); } @@ -564,13 +569,15 @@ internal static void SetReferences(this IDataReader reader, TopicIndex topics, b return null; } + var rawTopic = (ITopicBackingAccessor)addedTopic; + // Set the extended-attribute load state based on the database hint if (reader.GetNullableBoolean("HasExtendedAttributes") is true) { - addedTopic.Attributes.LoadState = LoadState.NotLoaded; + rawTopic.Attributes.LoadState = LoadState.NotLoaded; } // Set the children load state based on the database hint - addedTopic.Children.LoadState = reader.GetNullableBoolean("HasChildren") is true + rawTopic.Children.LoadState = reader.GetNullableBoolean("HasChildren") is true ? LoadState.NotLoaded : LoadState.Loaded; diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index 5b423f9e..5d7d6779 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -295,9 +295,11 @@ public override Topic Load(int topicId, DateTime version, Topic? referenceTopic | That's because there isn't a previous value associated with that key to overwrite the current value. In those cases, | those attributes must be manually removed. \-------------------------------------------------------------------------------------------------------------------------*/ - var orphanedAttributes = topic.Attributes.Where(a => a.LastModified > version).ToList(); + var rawTopic = (ITopicBackingAccessor)topic; + var orphanedAttributes = rawTopic.Attributes.Where(a => a.LastModified > version).ToList(); + foreach (var attribute in orphanedAttributes) { - topic.Attributes.Remove(attribute.Key); + rawTopic.Attributes.Remove(attribute.Key); } /*-------------------------------------------------------------------------------------------------------------------------- @@ -582,11 +584,12 @@ bool persistRelationships /*-------------------------------------------------------------------------------------------------------------------------- | Define variables \-------------------------------------------------------------------------------------------------------------------------*/ + var rawTopic = (ITopicBackingAccessor)topic; var isTopicDirty = topic.IsDirty(); - var areRelationshipsDirty = topic.Relationships.IsDirty(); - var areReferencesDirty = topic.References.IsDirty(); - var areAttributesDirty = topic.Attributes.IsDirty(true); - var extendedBoundaryLoaded = topic.Attributes.LoadState is LoadState.Loaded; + var areRelationshipsDirty = rawTopic.Relationships.IsDirty(); + var areReferencesDirty = rawTopic.References.IsDirty(); + var areAttributesDirty = rawTopic.Attributes.IsDirty(true); + var extendedBoundaryLoaded = rawTopic.Attributes.LoadState is LoadState.Loaded; var extendedAttributeList = GetAttributes(topic, isExtendedAttribute: true).ToList(); var indexedAttributeList = GetAttributes( topic : topic, @@ -904,11 +907,13 @@ private static void AddEnsureLoadedParameters(SqlCommand command, int topicId, T /// The SQL connection. private static void PersistRelationships(Topic topic, DateTime version, SqlConnection connection) { + var rawTopic = (ITopicBackingAccessor)topic; + /*-------------------------------------------------------------------------------------------------------------------------- | Return blank if the topic has no relations. \-------------------------------------------------------------------------------------------------------------------------*/ // return if the topic has no relations - if (topic.Relationships.Keys.Count == 0) { + if (rawTopic.Relationships.Keys.Count == 0) { return; } @@ -917,14 +922,14 @@ private static void PersistRelationships(Topic topic, DateTime version, SqlConne /*------------------------------------------------------------------------------------------------------------------------ | Iterate through each scope and persist to SQL \-----------------------------------------------------------------------------------------------------------------------*/ - foreach (var key in topic.Relationships.Keys) { + foreach (var key in rawTopic.Relationships.Keys) { using var targetIds = new TopicListDataTable(); using var command = new SqlCommand("UpdateRelationships", connection) { CommandType = CommandType.StoredProcedure }; - foreach (var targetTopic in topic.Relationships.GetValues(key)) { + foreach (var targetTopic in rawTopic.Relationships.GetValues(key)) { if (!targetTopic.IsNew) { targetIds.AddRow(targetTopic.Id); } @@ -935,7 +940,7 @@ private static void PersistRelationships(Topic topic, DateTime version, SqlConne command.AddParameter("RelationshipKey", key); command.AddParameter("RelatedTopics", targetIds); command.AddParameter("Version", version); - command.AddParameter("DeleteUnmatched", topic.Relationships.LoadState is LoadState.Loaded); + command.AddParameter("DeleteUnmatched", rawTopic.Relationships.LoadState is LoadState.Loaded); command.ExecuteNonQuery(); @@ -971,6 +976,8 @@ private static void PersistRelationships(Topic topic, DateTime version, SqlConne /// The SQL connection. private static void PersistReferences(Topic topic, DateTime version, SqlConnection connection) { + var rawTopic = (ITopicBackingAccessor)topic; + /*-------------------------------------------------------------------------------------------------------------------------- | Persist relations to database \-------------------------------------------------------------------------------------------------------------------------*/ @@ -981,7 +988,7 @@ private static void PersistReferences(Topic topic, DateTime version, SqlConnecti CommandType = CommandType.StoredProcedure }; - foreach (var relatedTopic in topic.References) { + foreach (var relatedTopic in rawTopic.References) { if (!relatedTopic.Value?.IsNew?? false) { references.AddRow(relatedTopic.Key, relatedTopic.Value!.Id); } @@ -991,7 +998,7 @@ private static void PersistReferences(Topic topic, DateTime version, SqlConnecti command.AddParameter("TopicID", topic.Id.ToString(CultureInfo.InvariantCulture)); command.AddParameter("ReferencedTopics", references); command.AddParameter("Version", version); - command.AddParameter("DeleteUnmatched", topic.References.LoadState is LoadState.Loaded); + command.AddParameter("DeleteUnmatched", rawTopic.References.LoadState is LoadState.Loaded); command.ExecuteNonQuery(); From 5cdf6446e87c8dcde3e8696a108581695e8cd81d Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 7 Jul 2026 15:06:37 -0700 Subject: [PATCH 096/337] Clear associations after successful database read Previously, when restoring a topic to a previous version, we cleared the `Relationships` and `References` before establishing the database connection, so that they could be repopulated with new content. This moves that within the connection and after the reader is executed so that this isn't performed unless we have successfully connected to the server and (presumably) retrieved the requested content. As part of this, I also clear the `Deferred` collections, as related to #111. They will be repopulated if there are any misses from the versioned associations. --- OnTopic.Data.Sql/SqlTopicRepository.cs | 21 ++++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index 5d7d6779..e6964055 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -236,13 +236,6 @@ public override Topic Load(int topicId, DateTime version, Topic? referenceTopic topic = referenceTopic.GetRootTopic().FindFirst(t => t.Id == topicId); } - if (topic is not null) { - foreach (var relationship in topic.Relationships) { - topic.Relationships.Clear(relationship.Key); - } - topic.References.Clear(); - } - /*-------------------------------------------------------------------------------------------------------------------------- | Establish database connection \-------------------------------------------------------------------------------------------------------------------------*/ @@ -266,11 +259,25 @@ public override Topic Load(int topicId, DateTime version, Topic? referenceTopic try { connection.Open(); using var reader = command.ExecuteReader(); + + // Clear existing associations before repopulating from the historical version + if (topic is not null) { + var rawExisting = (ITopicBackingAccessor)topic; + foreach (var relationship in rawExisting.Relationships) { + rawExisting.Relationships.Clear(relationship.Key); + } + rawExisting.Relationships.Deferred.Clear(); + rawExisting.References.Deferred.Clear(); + rawExisting.References.Clear(); + } + + // Load the historical version into the current topic graph topic = reader.LoadTopicGraph( topicId, referenceTopic, includeExternalReferences: referenceTopic is not null ); + } /*-------------------------------------------------------------------------------------------------------------------------- From dc975bf2398b11966e61d4ef335f5f0b5a3095aa Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 7 Jul 2026 16:16:30 -0700 Subject: [PATCH 097/337] Account for associations in `SqlTopicRepository` MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit In the `EnsureLoaded()` and `EnsureLoadedAsync()` in the `SqlTopicRepository`, we only need to include `@IncludeRelationships` or `@IncludeAssociations` if the caller requested `TopicPayload.Children`, as we ALWAYS load those when introducing new topics to the topic graph (3c278130), and then store them in the `Deferred` collections (f210866e, fce368be). If we're including new children in the call, however, those won't have that data and so, just like with `@IncludeExtendedAttributes`, they need to be accounted for. This gets confusing because `EnsureLoaded(Relationships)` or `EnsureLoaded(References)` don't actually do anything in the `SqlTopicRepository` right now. Those take the `Deferred` values, load them via `Load()≈, and incorporate them into the topic graph. Perhaps that should be in `SqlTopicRepository`, and I'll be revisiting that, but for now it means that those have no purpose here. As a result, I also added an early check-out at the top of `EnsureLoaded()` and `EnsureLoadedAsync()` if `TopicPayload` doesn't include `Children` or `ExtendedAttributes` so we avoid an unnecessary SQL calls. Finally, I also preemptively clear the `Deferred` collections on the parent/seed node if children are being loaded since, in that one case, it'll be processing those entries fresh. By clearing them, we avoid the possibility of creating duplicate entries—which doesn't hurt anything, but also doesn't add any value. As part of this, I made updates to a lot of the comments to help clarify this behavior. This contributes to #111. --- OnTopic.Data.Sql/SqlTopicRepository.cs | 68 +++++++++++++++++++------- 1 file changed, 49 insertions(+), 19 deletions(-) diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index e6964055..80742890 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -6,8 +6,6 @@ using System.Diagnostics.CodeAnalysis; using System.Globalization; using System.Text; -using OnTopic.Attributes; -using OnTopic.Collections.Specialized; using OnTopic.Data.Sql.Models; using OnTopic.Querying; using OnTopic.Repositories; @@ -408,6 +406,12 @@ public virtual void EnsureLoaded(Topic topic, TopicPayload payload) { return; } + // Relationships and References themselves not by SqlTopicRepository; exit early if that's all that's pending so we don't + // open a database connection unnecessarily + if (!payload.HasFlag(TopicPayload.Children) && !payload.HasFlag(TopicPayload.ExtendedAttributes)) { + return; + } + /*-------------------------------------------------------------------------------------------------------------------------- | Establish database connection \-------------------------------------------------------------------------------------------------------------------------*/ @@ -421,8 +425,13 @@ public virtual void EnsureLoaded(Topic topic, TopicPayload payload) { /*-------------------------------------------------------------------------------------------------------------------------- | Process database query + >--------------------------------------------------------------------------------------------------------------------------- + | Use the full live graph as the topic index so already-resident relationship targets are found without extra round-trips. + | When filling Children, associations for the parent/seed topic are re-fetched alongside the children's; stale deferred + | entries are cleared before processing to prevent duplicates from accumulating in the Deferred collection. \-------------------------------------------------------------------------------------------------------------------------*/ - var topics = new TopicIndex { [topic.Id] = topic }; + var topics = topic.GetRootTopic().GetTopicIndex(); + var rawTopic = (ITopicBackingAccessor)topic; try { @@ -452,6 +461,12 @@ public virtual void EnsureLoaded(Topic topic, TopicPayload payload) { reader.SetExtendedAttributes(topics, markDirty: false, preserveDirty: true); } + // Clear stale deferred entries on the parent/seed topic before its associations are re-processed alongside children + if (payload.HasFlag(TopicPayload.Children)) { + rawTopic.Relationships.Deferred.Clear(); + rawTopic.References.Deferred.Clear(); + } + // Relationships reader.NextResult(); while (reader.Read()) { @@ -472,10 +487,8 @@ public virtual void EnsureLoaded(Topic topic, TopicPayload payload) { /*-------------------------------------------------------------------------------------------------------------------------- | Mark confirmed payload as Loaded >--------------------------------------------------------------------------------------------------------------------------- - | Children is excluded: its LoadState is set inside FillChildren() after a successful fill, with each child's own - | Children.LoadState set based on its HasChildren bit. Relationships and References are excluded: their LoadState is set by - | SetRelationships() / SetReferences() based on whether each target is present in the graph (NotLoaded when absent), which - | blocks DeleteUnmatched on save and prevents silent data loss. + | Children is excluded: Its LoadState is set inside FillChildren() after a successful fill. Relationships and References + | are computed from Deferred.Count and require no explicit assignment here. Only Extended Attributes needs to be set. \-------------------------------------------------------------------------------------------------------------------------*/ topic.SetLoadState(payload & TopicPayload.ExtendedAttributes, LoadState.Loaded); @@ -505,6 +518,12 @@ public virtual async Task EnsureLoadedAsync(Topic topic, TopicPayload payload, C return; } + // Relationships and References themselves not by SqlTopicRepository; exit early if that's all that's pending so we don't + // open a database connection unnecessarily + if (!payload.HasFlag(TopicPayload.Children) && !payload.HasFlag(TopicPayload.ExtendedAttributes)) { + return; + } + /*-------------------------------------------------------------------------------------------------------------------------- | Establish database connection \-------------------------------------------------------------------------------------------------------------------------*/ @@ -518,8 +537,13 @@ public virtual async Task EnsureLoadedAsync(Topic topic, TopicPayload payload, C /*-------------------------------------------------------------------------------------------------------------------------- | Process database query + >--------------------------------------------------------------------------------------------------------------------------- + | Use the full live graph as the topic index so already-resident relationship targets are found without extra round-trips. + | When filling Children, associations for the parent/seed topic are re-fetched alongside the children's; stale deferred + | entries are cleared before processing to prevent duplicates from accumulating in the Deferred collection. \-------------------------------------------------------------------------------------------------------------------------*/ - var topics = new TopicIndex { [topic.Id] = topic }; + var topics = topic.GetRootTopic().GetTopicIndex(); + var rawTopic = (ITopicBackingAccessor)topic; try { @@ -527,7 +551,7 @@ public virtual async Task EnsureLoadedAsync(Topic topic, TopicPayload payload, C await connection.OpenAsync(cancellationToken).ConfigureAwait(false); using var reader = (SqlDataReader)await command.ExecuteReaderAsync(cancellationToken).ConfigureAwait(false); - // Children: Fill first result set; FillChildren() sets each child's Children.LoadState and marks the parent as Loaded + // Children: Fill first result set; FillChildrenAsync() sets each child's Children.LoadState and marks the parent Loaded if (payload.HasFlag(TopicPayload.Children)) { await reader.FillChildrenAsync(topic, topics, cancellationToken).ConfigureAwait(false); } @@ -549,6 +573,12 @@ public virtual async Task EnsureLoadedAsync(Topic topic, TopicPayload payload, C reader.SetExtendedAttributes(topics, markDirty: false, preserveDirty: true); } + // Clear stale deferred entries on the parent/seed topic before its associations are re-processed alongside children + if (payload.HasFlag(TopicPayload.Children)) { + rawTopic.Relationships.Deferred.Clear(); + rawTopic.References.Deferred.Clear(); + } + // Relationships await reader.NextResultAsync(cancellationToken).ConfigureAwait(false); while (await reader.ReadAsync(cancellationToken).ConfigureAwait(false)) { @@ -568,11 +598,9 @@ public virtual async Task EnsureLoadedAsync(Topic topic, TopicPayload payload, C /*-------------------------------------------------------------------------------------------------------------------------- | Mark confirmed payload as Loaded - >------------------------------------------------------------------------------------------------------------------------- - | Children is excluded: its LoadState is set inside FillChildrenAsync() after a successful fill, with each child's own - | Children.LoadState set based on its HasChildren bit. Relationships and References are excluded: their LoadState is set by - | SetRelationships() / SetReferences() based on whether each target is present in the graph (NotLoaded when absent), which - | blocks DeleteUnmatched on save and prevents silent data loss. + >--------------------------------------------------------------------------------------------------------------------------- + | Children is excluded: Its LoadState is set inside FillChildren() after a successful fill. Relationships and References + | are computed from Deferred.Count and require no explicit assignment here. Only Extended Attributes needs to be set. \-------------------------------------------------------------------------------------------------------------------------*/ topic.SetLoadState(payload & TopicPayload.ExtendedAttributes, LoadState.Loaded); @@ -881,8 +909,9 @@ protected override sealed void DeleteTopic(Topic topic) { /// /// Scope is always None (i.e., a single node) for resolver fills, as the caller is already in the graph. is hardcoded to false here because its fill path is not yet implemented; once - /// it is, this method will map it from the flag. Indexed attributes are only requested when - /// filling the boundary. + /// it is, this method will map it from the flag. Indexed attributes and associations are only + /// requested when filling the boundary, as they are otherwise always loaded as part of + /// the initial for existing topics. /// private static void AddEnsureLoadedParameters(SqlCommand command, int topicId, TopicPayload payload) { @@ -894,11 +923,12 @@ private static void AddEnsureLoadedParameters(SqlCommand command, int topicId, T command.AddParameter("LoadAscendants", false); command.AddParameter("LoadChildren", payload.HasFlag(TopicPayload.Children)); - // Payload: Include only what the requested payload require + // Payload: Include only what the requested payload requires; relationships and references are loaded during the initial + // Load() call, so they do not need to be re-fetched command.AddParameter("IncludeIndexed", payload.HasFlag(TopicPayload.Children)); command.AddParameter("IncludeExtended", payload.HasFlag(TopicPayload.ExtendedAttributes)); - command.AddParameter("IncludeRelationships", payload.HasFlag(TopicPayload.Relationships)); - command.AddParameter("IncludeReferences", payload.HasFlag(TopicPayload.References)); + command.AddParameter("IncludeRelationships", payload.HasFlag(TopicPayload.Children)); + command.AddParameter("IncludeReferences", payload.HasFlag(TopicPayload.Children)); command.AddParameter("IncludeHistory", false); } From 2e4b125193aadae0c662e7d74bad005c11d24747 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 7 Jul 2026 16:21:17 -0700 Subject: [PATCH 098/337] Always load ancestors unless loading the root MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Previously, I ensured that ascendants were loaded if we were calling a topic other than the root and the `referenceTopic` was null (19688765). The assumption was that `referenceTopic` would include the parent and, therefore, the loaded topic would have an existing home in the topic graph without needing the ascendant context. That assumption is invalid, and especially in context of lazy loading (#111). The `referenceTopic` is intended to connect this back to a graph, but it could still be well below any parent nodes that it needs to connect to that graph. As such, we _always_ need this, unless we're pulling the root node. (Even with a root node, this wouldn't hurt anything—there simply wouldn't be any data—but might as well save that quick query if we know to that to be the case, and especially given this is an existing capability.) --- OnTopic.Data.Sql/SqlTopicRepository.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index 80742890..d591b0f3 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -141,7 +141,7 @@ public override Topic Load( \-------------------------------------------------------------------------------------------------------------------------*/ command.AddParameter("TopicID", topicId); command.AddParameter("LoadDescendants", isRecursive); - command.AddParameter("LoadAscendants", topicId >= 0 && referenceTopic is null); + command.AddParameter("LoadAscendants", topicId >= 0); command.AddParameter("IncludeExtended", payload.HasFlag(TopicPayload.ExtendedAttributes)); command.AddParameter("IncludeRelationships", true); command.AddParameter("IncludeReferences", true); From 257545eba9ce74ee2b0b9bbd108095dd81efbbdc Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 7 Jul 2026 16:33:59 -0700 Subject: [PATCH 099/337] Dynamically load associations in `EnsureLoad()` This is the core implementation of `EnsureLoaded()` and `EnsureLoadedAsync()` for `TopicPayload.Relationships` and/or `TopicPayload.References`, and thus a key deliverable for the lazy-loading project (#111). In `Load()`, the `Relationships` and `References` arguments instruct the stored procedure to return the keys and topic IDs for those alongside topics (3c278130), which is a cheap call and we can store orphans in `Deferred` (f210866e, fce368be) without needing to look them up again. In `EnsureLoaded()`, instead, we want to ensure that those topic IDs resolve to actual topics in the topic tree. That's a different task entirely. For now, this is is exclusively being implemented in `CachedTopicRepository`, not the underlying e.g., `SqlTopicRepository` (dc975bf2), though I'll almost certainly want to revisit that later, ideally by some type of base class that supports all repositories. In the meanwhile, however, this establishes the business logic and allows this to work in real-world scenarios. --- OnTopic.Data.Caching/CachedTopicRepository.cs | 52 +++++++++++++++++-- 1 file changed, 49 insertions(+), 3 deletions(-) diff --git a/OnTopic.Data.Caching/CachedTopicRepository.cs b/OnTopic.Data.Caching/CachedTopicRepository.cs index 8b2f1911..a9c2c3dc 100644 --- a/OnTopic.Data.Caching/CachedTopicRepository.cs +++ b/OnTopic.Data.Caching/CachedTopicRepository.cs @@ -3,6 +3,7 @@ | Client Ignia, LLC | Project Topics Library \=============================================================================================================================*/ +using OnTopic.Associations; using OnTopic.Internal.Diagnostics; using OnTopic.Querying; using OnTopic.Repositories; @@ -265,12 +266,15 @@ public virtual void EnsureLoaded(Topic topic, TopicPayload payload) { } /*-------------------------------------------------------------------------------------------------------------------------- - | Delegate to inner resolver + | Delegate to the inner resolver; captures missing targets in the Deferred collections \-------------------------------------------------------------------------------------------------------------------------*/ if (TopicRepository is ITopicLoadResolver resolver) { resolver.EnsureLoaded(topic, payload); } + // Resolve any deferred relationship/reference targets through the cache layer + ResolveDeferredAssociations(topic, payload); + // Update flat index and stamp resolver for any newly loaded children if (payload.HasFlag(TopicPayload.Children)) { lock (_syncLock) { @@ -301,12 +305,15 @@ public virtual Task EnsureLoadedAsync(Topic topic, TopicPayload payload, Cancell } /*-------------------------------------------------------------------------------------------------------------------------- - | Delegate to inner resolver + | Delegate to the inner resolver; captures missing targets in the Deferred collections \-------------------------------------------------------------------------------------------------------------------------*/ if (TopicRepository is ITopicLoadResolver resolver) { resolver.EnsureLoaded(topic, payload); } + // Resolve any deferred relationship/reference targets through the cache layer + ResolveDeferredAssociations(topic, payload); + // Update flat index and stamp resolver for any newly loaded children if (payload.HasFlag(TopicPayload.Children)) { lock (_syncLock) { @@ -421,7 +428,46 @@ protected override void OnTopicRenamed(TopicRenameEventArgs args) { | METHODS: PRIVATE \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Removes stale _topicByKey entries for and its descendants by swapping the by + /// loading each through the cache layer's own Load(), which checks the index before falling through to the + /// underlying persistence store. Targets that cannot be found are treated as stale references to deleted topics and + /// discarded; the getter clears any remaining entries after this method returns. + /// + /// The topic whose deferred associations should be resolved. + /// + /// The payload flags that were requested; only and are acted upon. + /// + private void ResolveDeferredAssociations(Topic topic, TopicPayload payload) { + + var rawTopic = (ITopicBackingAccessor)topic; + + // Resolve deferred relationship targets; unresolvable targets are treated as stale and discarded + if (payload.HasFlag(TopicPayload.Relationships) && rawTopic.Relationships.Deferred.Count > 0) { + foreach (var deferred in rawTopic.Relationships.Deferred.ToArray()) { + var target = Load(deferred.TopicId); + // SetValue removes the matching Deferred entry; stale entries are cleared by the Topic getter + if (target is not null) { + rawTopic.Relationships.SetValue(deferred.Key, target, markDirty: false); + } + } + } + + // Resolve deferred reference targets; unresolvable targets are treated as stale and discarded + if (payload.HasFlag(TopicPayload.References) && rawTopic.References.Deferred.Count > 0) { + foreach (var deferred in rawTopic.References.Deferred.ToArray()) { + var target = Load(deferred.TopicId); + // SetValue removes the matching Deferred entry; stale entries are cleared by the Topic getter + if (target is not null) { + rawTopic.References.SetValue(deferred.Key, target, markDirty: false); + } + } + } + + } + + /// + /// Removes stale _topicByKey entries for and its descendants by swapping the prefix for the current one, then reindexes the subtree under its current unique keys. /// private void RekeyTopicSubtree(Topic topic, string oldRootUniqueKey) { From f7a86d8d269182c6a1eb8d0b152271c23d372fde Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 7 Jul 2026 16:37:09 -0700 Subject: [PATCH 100/337] Trigger lazy-loading associations from `Topic` This is the final wiring required for lazy-loading associations (#111)! Now, calls to `Topic.Relationships` or `Topic.References()` will trigger the lazy-loading implementation in e.g., `CachedTopicRepository` (257545eb), assuming it's being used. I need to revisit the strategy here for other cases (e.g., where someone is using `SqlTopicRepository` without the `CachedTopicRepository` for some reason, such as a temporary in-memory programmatic crawl), but this satisfies the core use case that most implementations will follow. --- OnTopic/Topic.cs | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/OnTopic/Topic.cs b/OnTopic/Topic.cs index 88218913..49f27e3e 100644 --- a/OnTopic/Topic.cs +++ b/OnTopic/Topic.cs @@ -293,7 +293,7 @@ public void EnsureLoaded(TopicPayload payload) { /*-------------------------------------------------------------------------------------------------------------------------- | Filter to payload that are not yet loaded \-------------------------------------------------------------------------------------------------------------------------*/ - payload = FilterPayload(payload); + payload = FilterPayload(payload); if (payload is TopicPayload.None) { return; @@ -321,7 +321,7 @@ public Task EnsureLoadedAsync(TopicPayload payload, CancellationToken cancellati /*-------------------------------------------------------------------------------------------------------------------------- | Filter to payload that are not yet loaded \-------------------------------------------------------------------------------------------------------------------------*/ - payload = FilterPayload(payload); + payload = FilterPayload(payload); if (payload is TopicPayload.None) { return Task.CompletedTask; @@ -952,6 +952,10 @@ public Topic? DerivedTopic { /// The current 's relationships. public TopicRelationshipMultiMap Relationships { get { + if (_relationships.LoadState is LoadState.NotLoaded && Resolver is not null) { + Resolver.EnsureLoaded(this, TopicPayload.Relationships); + _relationships.Deferred.Clear(); + } return _relationships; } } @@ -969,6 +973,10 @@ public TopicRelationshipMultiMap Relationships { /// The current 's references. public TopicReferenceCollection References { get { + if (_references.LoadState is LoadState.NotLoaded && Resolver is not null) { + Resolver.EnsureLoaded(this, TopicPayload.References); + _references.Deferred.Clear(); + } return _references; } } From 6e9cde8b3cdeea7cb61c4fdb7ac3b1884ff3657c Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 7 Jul 2026 17:13:28 -0700 Subject: [PATCH 101/337] Ensure `Deferred` are cleared in prep for new test This clears the new `Deferred` collection (f210866e, fce368be) at the end of each `EnsureLoaded()` call to prevent test data from infecting subsequent calls to this shared resource. If this becomes a problem, we'll need to instead spin up a new instance for each test. This lays the foundation for testing the lazy-loading implementation (#111). --- OnTopic.TestDoubles/StubTopicRepository.cs | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/OnTopic.TestDoubles/StubTopicRepository.cs b/OnTopic.TestDoubles/StubTopicRepository.cs index 3ad3d9cb..e9b4af18 100644 --- a/OnTopic.TestDoubles/StubTopicRepository.cs +++ b/OnTopic.TestDoubles/StubTopicRepository.cs @@ -220,6 +220,15 @@ public virtual void EnsureLoaded(Topic topic, TopicPayload payload) { \-------------------------------------------------------------------------------------------------------------------------*/ topic.SetLoadState(payload, LoadState.Loaded); + // Relationships and References are computed from Deferred.Count; clear any test-seeded deferred entries to express Loaded + var rawTopic = (ITopicBackingAccessor)topic; + if (payload.HasFlag(TopicPayload.Relationships)) { + rawTopic.Relationships.Deferred.Clear(); + } + if (payload.HasFlag(TopicPayload.References)) { + rawTopic.References.Deferred.Clear(); + } + } /// From aff64914dcf901802d3d0c8bb7296686e77d8b6f Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 7 Jul 2026 17:23:06 -0700 Subject: [PATCH 102/337] Prefer collection expressions over explicit `new` --- OnTopic.Tests/SqlTopicRepositoryTest.cs | 28 ++++++++++++------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/OnTopic.Tests/SqlTopicRepositoryTest.cs b/OnTopic.Tests/SqlTopicRepositoryTest.cs index 841032e8..87d2a4d1 100644 --- a/OnTopic.Tests/SqlTopicRepositoryTest.cs +++ b/OnTopic.Tests/SqlTopicRepositoryTest.cs @@ -90,7 +90,7 @@ public void LoadTopicGraph_WithAttributes_ReturnsAttributes() { topics.AddRow(1, "Root", "Container", null); attributes.AddRow(1, "Test", "Value"); - using var tableReader = new DataTableReader(new DataTable[] { topics, attributes }); + using var tableReader = new DataTableReader([topics, attributes]); var topic = tableReader.LoadTopicGraph(); @@ -120,7 +120,7 @@ public void LoadTopicGraph_WithNullAttributes_RemovesAttribute() { topics.AddRow(1, "Root", "Container"); attributes.AddRow(1, "Test", null); - using var tableReader = new DataTableReader(new DataTable[] { topics, attributes }); + using var tableReader = new DataTableReader([topics, attributes]); tableReader.LoadTopicGraph(referenceTopic: topic); @@ -146,7 +146,7 @@ public void LoadTopicGraph_WithRelationship_ReturnsRelationship() { topics.AddRow(2, "Web", "Container", 1); relationships.AddRow(1, "Test", 2, false); - using var tableReader = new DataTableReader(new DataTable[] { topics, empty, empty, relationships }); + using var tableReader = new DataTableReader([topics, empty, empty, relationships]); var topic = tableReader.LoadTopicGraph(); @@ -174,7 +174,7 @@ public void LoadTopicGraph_WithMissingRelationship_NotFullyLoaded() { topics.AddRow(1, "Root", "Container", null); relationships.AddRow(1, "Test", 2, false); - using var tableReader = new DataTableReader(new DataTable[] { topics, empty, empty, relationships }); + using var tableReader = new DataTableReader([topics, empty, empty, relationships]); var topic = tableReader.LoadTopicGraph(); @@ -203,7 +203,7 @@ public void LoadTopicGraph_WithReference_ReturnsReference() { topics.AddRow(2, "Web", "Container", 1); references.AddRow(1, "Test", 2); - using var tableReader = new DataTableReader(new DataTable[] { topics, empty, empty, empty, references }); + using var tableReader = new DataTableReader([topics, empty, empty, empty, references]); var topic = tableReader.LoadTopicGraph(); @@ -233,7 +233,7 @@ public void LoadTopicGraph_WithExternalReference_ReturnsReference() { topics.AddRow(1, "Root", "Container", null); references.AddRow(1, "Test", 2); - using var tableReader = new DataTableReader(new DataTable[] { topics, empty, empty, empty, references }); + using var tableReader = new DataTableReader([topics, empty, empty, empty, references]); var topic = tableReader.LoadTopicGraph(1, referenceTopic, false); @@ -267,7 +267,7 @@ public void LoadTopicGraph_WithDeletedReference_RemovesExistingReference() { topics.AddRow(1, "Web", "Container", null); references.AddRow(1, "Reference", null); - using var tableReader = new DataTableReader(new DataTable[] { topics, empty, empty, empty, references }); + using var tableReader = new DataTableReader([topics, empty, empty, empty, references]); tableReader.LoadTopicGraph(1, referenceTopic, false); @@ -293,7 +293,7 @@ public void LoadTopicGraph_WithMissingReference_NotFullyLoaded() { topics.AddRow(1, "Root", "Container", null); references.AddRow(1, "Test", 2); - using var tableReader = new DataTableReader(new DataTable[] { topics, empty, empty, empty, references }); + using var tableReader = new DataTableReader([topics, empty, empty, empty, references]); var topic = tableReader.LoadTopicGraph(); @@ -325,7 +325,7 @@ public void LoadTopicGraph_WithDeletedRelationship_RemovesRelationship() { relationships.AddRow(2, "Test", 3, true); - using var tableReader = new DataTableReader(new DataTable[] { empty, empty, empty, relationships }); + using var tableReader = new DataTableReader([empty, empty, empty, relationships]); tableReader.LoadTopicGraph(referenceTopic: related); @@ -352,7 +352,7 @@ public void LoadTopicGraph_IndexedOnlyWithRelationship_ReturnsLoaded() { topics.AddRow(2, "Web", "Container", 1, hasExtendedAttributes: false); relationships.AddRow(1, "Test", 2, false); - using var tableReader = new DataTableReader(new DataTable[] { topics, empty, empty, relationships }); + using var tableReader = new DataTableReader([topics, empty, empty, relationships]); var topic = tableReader.LoadTopicGraph(); @@ -379,7 +379,7 @@ public void LoadTopicGraph_IndexedOnlyWithMissingRelationship_ReturnsNotLoaded() topics.AddRow(1, "Root", "Container", null, hasExtendedAttributes: true); relationships.AddRow(1, "Test", 99, false); - using var tableReader = new DataTableReader(new DataTable[] { topics, empty, empty, relationships }); + using var tableReader = new DataTableReader([topics, empty, empty, relationships]); var topic = tableReader.LoadTopicGraph(); @@ -406,7 +406,7 @@ public void LoadTopicGraph_IndexedOnlyWithReference_ReturnsLoaded() { topics.AddRow(2, "Web", "Container", 1, hasExtendedAttributes: false); references.AddRow(1, "Test", 2); - using var tableReader = new DataTableReader(new DataTable[] { topics, empty, empty, empty, references }); + using var tableReader = new DataTableReader([topics, empty, empty, empty, references]); var topic = tableReader.LoadTopicGraph(); @@ -433,7 +433,7 @@ public void LoadTopicGraph_IndexedOnlyWithMissingReference_ReturnsNotLoaded() { topics.AddRow(1, "Root", "Container", null, hasExtendedAttributes: true); references.AddRow(1, "Test", 99); - using var tableReader = new DataTableReader(new DataTable[] { topics, empty, empty, empty, references }); + using var tableReader = new DataTableReader([topics, empty, empty, empty, references]); var topic = tableReader.LoadTopicGraph(); @@ -459,7 +459,7 @@ public void LoadTopicGraph_WithVersionHistory_ReturnsVersions() { topics.AddRow(1, "Root", "Container", null); versions.AddRow(1, DateTime.MinValue); - using var tableReader = new DataTableReader(new DataTable[] { topics, empty, empty, empty, empty, versions }); + using var tableReader = new DataTableReader([topics, empty, empty, empty, empty, versions]); var topic = tableReader.LoadTopicGraph(); From 2e536beddd6defdf7cff0dcc9a4d4cce786c6863 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 7 Jul 2026 21:56:40 -0700 Subject: [PATCH 103/337] Use `IsTopic()` to bypass lazy-loading MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The prior setup of the tests will now trigger lazy-loading. In practice, at this point, that doesn't hurt anything—but it should, and will in subsequent test versions. This prevents that eventuality. This contributes to the testing of #111. --- OnTopic.Tests/SqlTopicRepositoryTest.cs | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/OnTopic.Tests/SqlTopicRepositoryTest.cs b/OnTopic.Tests/SqlTopicRepositoryTest.cs index 87d2a4d1..58a0855b 100644 --- a/OnTopic.Tests/SqlTopicRepositoryTest.cs +++ b/OnTopic.Tests/SqlTopicRepositoryTest.cs @@ -9,6 +9,7 @@ using OnTopic.Associations; using OnTopic.Data.Sql; using OnTopic.Data.Sql.Models; +using OnTopic.Repositories; using OnTopic.Tests.Schemas; using Xunit; using TopicReferencesDataTable = OnTopic.Tests.Schemas.TopicReferencesDataTable; @@ -153,7 +154,7 @@ public void LoadTopicGraph_WithRelationship_ReturnsRelationship() { Assert.NotNull(topic); Assert.Equal(1, topic?.Id); Assert.Equal(2, topic?.Relationships.GetValues("Test").FirstOrDefault()?.Id); - Assert.Equal(LoadState.Loaded, topic?.Relationships.LoadState); + Assert.True(topic?.IsLoaded(TopicPayload.Relationships)); } @@ -181,7 +182,7 @@ public void LoadTopicGraph_WithMissingRelationship_NotFullyLoaded() { Assert.NotNull(topic); Assert.Equal(1, topic.Id); Assert.Empty(topic.Relationships); - Assert.Equal(LoadState.NotLoaded, topic.Relationships.LoadState); + Assert.False(topic.IsLoaded(TopicPayload.Relationships)); } @@ -240,7 +241,7 @@ public void LoadTopicGraph_WithExternalReference_ReturnsReference() { Assert.NotNull(topic); Assert.Equal(1, topic?.Id); Assert.Equal(2, topic?.References.GetValue("Test")?.Id); - Assert.Equal(LoadState.Loaded, topic?.References.LoadState); + Assert.True(topic?.IsLoaded(TopicPayload.References)); Assert.False(topic?.References.IsDirty()); } @@ -300,7 +301,7 @@ public void LoadTopicGraph_WithMissingReference_NotFullyLoaded() { Assert.NotNull(topic); Assert.Equal(1, topic.Id); Assert.Empty(topic.References); - Assert.Equal(LoadState.NotLoaded, topic.References.LoadState); + Assert.False(topic.IsLoaded(TopicPayload.References)); } @@ -357,7 +358,7 @@ public void LoadTopicGraph_IndexedOnlyWithRelationship_ReturnsLoaded() { var topic = tableReader.LoadTopicGraph(); Assert.NotNull(topic); - Assert.Equal(LoadState.Loaded, topic?.Relationships.LoadState); + Assert.True(topic.IsLoaded(TopicPayload.Relationships)); } @@ -384,7 +385,7 @@ public void LoadTopicGraph_IndexedOnlyWithMissingRelationship_ReturnsNotLoaded() var topic = tableReader.LoadTopicGraph(); Assert.NotNull(topic); - Assert.Equal(LoadState.NotLoaded, topic!.Relationships.LoadState); + Assert.False(topic!.IsLoaded(TopicPayload.Relationships)); } @@ -411,7 +412,7 @@ public void LoadTopicGraph_IndexedOnlyWithReference_ReturnsLoaded() { var topic = tableReader.LoadTopicGraph(); Assert.NotNull(topic); - Assert.Equal(LoadState.Loaded, topic?.References.LoadState); + Assert.True(topic.IsLoaded(TopicPayload.References)); } @@ -438,7 +439,7 @@ public void LoadTopicGraph_IndexedOnlyWithMissingReference_ReturnsNotLoaded() { var topic = tableReader.LoadTopicGraph(); Assert.NotNull(topic); - Assert.Equal(LoadState.NotLoaded, topic!.References.LoadState); + Assert.False(topic!.IsLoaded(TopicPayload.References)); } @@ -490,7 +491,7 @@ public void LoadTopicGraph_WithExtendedDeferredAndBlob_ReturnsNotLoaded() { var topic = tableReader.LoadTopicGraph(); Assert.NotNull(topic); - Assert.Equal(LoadState.NotLoaded, topic.Attributes.LoadState); + Assert.False(topic.IsLoaded(TopicPayload.ExtendedAttributes)); } @@ -561,7 +562,7 @@ public void LoadTopicGraph_WithHasChildrenFalse_ReturnsChildrenLoaded() { var topic = tableReader.LoadTopicGraph(1); - Assert.Equal(LoadState.Loaded, topic?.Children.LoadState); + Assert.True(topic?.IsLoaded(TopicPayload.Children)); } @@ -585,7 +586,7 @@ public void LoadTopicGraph_WithHasChildrenAndLoadedChildren_ReturnsChildrenLoade var topic = tableReader.LoadTopicGraph(1); - Assert.Equal(LoadState.Loaded, topic?.Children.LoadState); + Assert.True(topic?.IsLoaded(TopicPayload.Children)); } From e8f455f5489536514aebd09202cdbb5c5ed5f1cb Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 7 Jul 2026 22:18:19 -0700 Subject: [PATCH 104/337] Don't use null-forgiving operator after null check In xUnit 3.x, the `Assert.NotNull()` establishes that the variable isn't null (as it should) and thus we can remove the null-forgiving or assurance operators. --- OnTopic.Tests/SqlTopicRepositoryTest.cs | 34 ++++++++++++------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/OnTopic.Tests/SqlTopicRepositoryTest.cs b/OnTopic.Tests/SqlTopicRepositoryTest.cs index 58a0855b..1ba2b1ea 100644 --- a/OnTopic.Tests/SqlTopicRepositoryTest.cs +++ b/OnTopic.Tests/SqlTopicRepositoryTest.cs @@ -44,7 +44,7 @@ public void LoadTopicGraph_WithTopic_ReturnsTopic() { var topic = tableReader.LoadTopicGraph(); Assert.NotNull(topic); - Assert.Equal(1, topic?.Id); + Assert.Equal(1, topic.Id); } @@ -96,8 +96,8 @@ public void LoadTopicGraph_WithAttributes_ReturnsAttributes() { var topic = tableReader.LoadTopicGraph(); Assert.NotNull(topic); - Assert.Equal(1, topic?.Id); - Assert.Equal("Value", topic?.Attributes.GetValue("Test")); + Assert.Equal(1, topic.Id); + Assert.Equal("Value", topic.Attributes.GetValue("Test")); } @@ -152,9 +152,9 @@ public void LoadTopicGraph_WithRelationship_ReturnsRelationship() { var topic = tableReader.LoadTopicGraph(); Assert.NotNull(topic); - Assert.Equal(1, topic?.Id); - Assert.Equal(2, topic?.Relationships.GetValues("Test").FirstOrDefault()?.Id); - Assert.True(topic?.IsLoaded(TopicPayload.Relationships)); + Assert.Equal(1, topic.Id); + Assert.Equal(2, topic.Relationships.GetValues("Test").FirstOrDefault()?.Id); + Assert.True(topic.IsLoaded(TopicPayload.Relationships)); } @@ -209,9 +209,9 @@ public void LoadTopicGraph_WithReference_ReturnsReference() { var topic = tableReader.LoadTopicGraph(); Assert.NotNull(topic); - Assert.Equal(1, topic?.Id); - Assert.Equal(2, topic?.References.GetValue("Test")?.Id); - Assert.True(topic?.References.IsDirty()); + Assert.Equal(1, topic.Id); + Assert.Equal(2, topic.References.GetValue("Test")?.Id); + Assert.True(topic.References.IsDirty()); } @@ -239,10 +239,10 @@ public void LoadTopicGraph_WithExternalReference_ReturnsReference() { var topic = tableReader.LoadTopicGraph(1, referenceTopic, false); Assert.NotNull(topic); - Assert.Equal(1, topic?.Id); - Assert.Equal(2, topic?.References.GetValue("Test")?.Id); - Assert.True(topic?.IsLoaded(TopicPayload.References)); - Assert.False(topic?.References.IsDirty()); + Assert.Equal(1, topic.Id); + Assert.Equal(2, topic.References.GetValue("Test")?.Id); + Assert.True(topic.IsLoaded(TopicPayload.References)); + Assert.False(topic.References.IsDirty()); } @@ -385,7 +385,7 @@ public void LoadTopicGraph_IndexedOnlyWithMissingRelationship_ReturnsNotLoaded() var topic = tableReader.LoadTopicGraph(); Assert.NotNull(topic); - Assert.False(topic!.IsLoaded(TopicPayload.Relationships)); + Assert.False(topic.IsLoaded(TopicPayload.Relationships)); } @@ -827,7 +827,7 @@ public void SqlCommand_AddParameter_DateTime() { public void SqlCommand_AddParameter_DataTable() { var command = new SqlCommand(); - var dataTable = new Data.Sql.Models.TopicListDataTable(); + var dataTable = new TopicListDataTable(); command.AddParameter("Relationships", dataTable); @@ -890,8 +890,8 @@ public void SqlCommand_AddOutputParameter_ReturnCode() { Assert.Single(command.Parameters); Assert.True(command.Parameters.Contains("@TopicId")); Assert.Equal(5, command.GetReturnCode("TopicId")); - Assert.Equal(ParameterDirection.ReturnValue, sqlParameter?.Direction); - Assert.Equal(SqlDbType.Int, sqlParameter?.SqlDbType); + Assert.Equal(ParameterDirection.ReturnValue, sqlParameter.Direction); + Assert.Equal(SqlDbType.Int, sqlParameter.SqlDbType); command.Dispose(); From e39b605525a53d8aa9078a6da57dad7d779c470c Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 7 Jul 2026 22:20:57 -0700 Subject: [PATCH 105/337] Remove implicit nulls for `parentId` The `parentId` parameter of `AddRow()` is `null` by default, so doesn't need to be explicitly defined. --- OnTopic.Tests/SqlTopicRepositoryTest.cs | 40 ++++++++++++------------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/OnTopic.Tests/SqlTopicRepositoryTest.cs b/OnTopic.Tests/SqlTopicRepositoryTest.cs index 1ba2b1ea..b22587cd 100644 --- a/OnTopic.Tests/SqlTopicRepositoryTest.cs +++ b/OnTopic.Tests/SqlTopicRepositoryTest.cs @@ -37,7 +37,7 @@ public void LoadTopicGraph_WithTopic_ReturnsTopic() { using var topics = new TopicsDataTable(); - topics.AddRow(1, "Root", "Container", null); + topics.AddRow(1, "Root", "Container"); using var tableReader = new DataTableReader(topics); @@ -88,7 +88,7 @@ public void LoadTopicGraph_WithAttributes_ReturnsAttributes() { using var topics = new TopicsDataTable(); using var attributes = new AttributesDataTable(); - topics.AddRow(1, "Root", "Container", null); + topics.AddRow(1, "Root", "Container"); attributes.AddRow(1, "Test", "Value"); using var tableReader = new DataTableReader([topics, attributes]); @@ -143,7 +143,7 @@ public void LoadTopicGraph_WithRelationship_ReturnsRelationship() { using var empty = new AttributesDataTable(); using var relationships = new RelationshipsDataTable(); - topics.AddRow(1, "Root", "Container", null); + topics.AddRow(1, "Root", "Container"); topics.AddRow(2, "Web", "Container", 1); relationships.AddRow(1, "Test", 2, false); @@ -172,7 +172,7 @@ public void LoadTopicGraph_WithMissingRelationship_NotFullyLoaded() { using var empty = new AttributesDataTable(); using var relationships = new RelationshipsDataTable(); - topics.AddRow(1, "Root", "Container", null); + topics.AddRow(1, "Root", "Container"); relationships.AddRow(1, "Test", 2, false); using var tableReader = new DataTableReader([topics, empty, empty, relationships]); @@ -200,7 +200,7 @@ public void LoadTopicGraph_WithReference_ReturnsReference() { using var empty = new AttributesDataTable(); using var references = new TopicReferencesDataTable(); - topics.AddRow(1, "Root", "Container", null); + topics.AddRow(1, "Root", "Container"); topics.AddRow(2, "Web", "Container", 1); references.AddRow(1, "Test", 2); @@ -231,7 +231,7 @@ public void LoadTopicGraph_WithExternalReference_ReturnsReference() { var referenceTopic = new Topic("Web", "Container", null, 2); - topics.AddRow(1, "Root", "Container", null); + topics.AddRow(1, "Root", "Container"); references.AddRow(1, "Test", 2); using var tableReader = new DataTableReader([topics, empty, empty, empty, references]); @@ -265,7 +265,7 @@ public void LoadTopicGraph_WithDeletedReference_RemovesExistingReference() { referenceTopic.References.SetValue("Reference", referenceTopic); - topics.AddRow(1, "Web", "Container", null); + topics.AddRow(1, "Web", "Container"); references.AddRow(1, "Reference", null); using var tableReader = new DataTableReader([topics, empty, empty, empty, references]); @@ -291,7 +291,7 @@ public void LoadTopicGraph_WithMissingReference_NotFullyLoaded() { using var empty = new AttributesDataTable(); using var references = new TopicReferencesDataTable(); - topics.AddRow(1, "Root", "Container", null); + topics.AddRow(1, "Root", "Container"); references.AddRow(1, "Test", 2); using var tableReader = new DataTableReader([topics, empty, empty, empty, references]); @@ -349,7 +349,7 @@ public void LoadTopicGraph_IndexedOnlyWithRelationship_ReturnsLoaded() { using var empty = new AttributesDataTable(); using var relationships = new RelationshipsDataTable(); - topics.AddRow(1, "Root", "Container", null, hasExtendedAttributes: true); + topics.AddRow(1, "Root", "Container", hasExtendedAttributes: true); topics.AddRow(2, "Web", "Container", 1, hasExtendedAttributes: false); relationships.AddRow(1, "Test", 2, false); @@ -377,7 +377,7 @@ public void LoadTopicGraph_IndexedOnlyWithMissingRelationship_ReturnsNotLoaded() using var empty = new AttributesDataTable(); using var relationships = new RelationshipsDataTable(); - topics.AddRow(1, "Root", "Container", null, hasExtendedAttributes: true); + topics.AddRow(1, "Root", "Container", hasExtendedAttributes: true); relationships.AddRow(1, "Test", 99, false); using var tableReader = new DataTableReader([topics, empty, empty, relationships]); @@ -403,7 +403,7 @@ public void LoadTopicGraph_IndexedOnlyWithReference_ReturnsLoaded() { using var empty = new AttributesDataTable(); using var references = new TopicReferencesDataTable(); - topics.AddRow(1, "Root", "Container", null, hasExtendedAttributes: true); + topics.AddRow(1, "Root", "Container", hasExtendedAttributes: true); topics.AddRow(2, "Web", "Container", 1, hasExtendedAttributes: false); references.AddRow(1, "Test", 2); @@ -431,7 +431,7 @@ public void LoadTopicGraph_IndexedOnlyWithMissingReference_ReturnsNotLoaded() { using var empty = new AttributesDataTable(); using var references = new TopicReferencesDataTable(); - topics.AddRow(1, "Root", "Container", null, hasExtendedAttributes: true); + topics.AddRow(1, "Root", "Container", hasExtendedAttributes: true); references.AddRow(1, "Test", 99); using var tableReader = new DataTableReader([topics, empty, empty, empty, references]); @@ -439,7 +439,7 @@ public void LoadTopicGraph_IndexedOnlyWithMissingReference_ReturnsNotLoaded() { var topic = tableReader.LoadTopicGraph(); Assert.NotNull(topic); - Assert.False(topic!.IsLoaded(TopicPayload.References)); + Assert.False(topic.IsLoaded(TopicPayload.References)); } @@ -457,7 +457,7 @@ public void LoadTopicGraph_WithVersionHistory_ReturnsVersions() { using var empty = new AttributesDataTable(); using var versions = new VersionHistoryDataTable(); - topics.AddRow(1, "Root", "Container", null); + topics.AddRow(1, "Root", "Container"); versions.AddRow(1, DateTime.MinValue); using var tableReader = new DataTableReader([topics, empty, empty, empty, empty, versions]); @@ -484,7 +484,7 @@ public void LoadTopicGraph_WithExtendedDeferredAndBlob_ReturnsNotLoaded() { using var topics = new TopicsDataTable(); - topics.AddRow(1, "Root", "Container", null, hasExtendedAttributes: true); + topics.AddRow(1, "Root", "Container", hasExtendedAttributes: true); using var tableReader = new DataTableReader(topics); @@ -508,7 +508,7 @@ public void LoadTopicGraph_WithExtendedDeferredAndNoBlob_ReturnsLoaded() { using var topics = new TopicsDataTable(); - topics.AddRow(1, "Root", "Container", null, hasExtendedAttributes: false); + topics.AddRow(1, "Root", "Container", hasExtendedAttributes: false); using var tableReader = new DataTableReader(topics); @@ -532,7 +532,7 @@ public void LoadTopicGraph_WithExtendedIncludedAndBlob_ReturnsLoaded() { using var topics = new TopicsDataTable(); - topics.AddRow(1, "Root", "Container", null); + topics.AddRow(1, "Root", "Container"); using var tableReader = new DataTableReader(topics); @@ -556,7 +556,7 @@ public void LoadTopicGraph_WithHasChildrenFalse_ReturnsChildrenLoaded() { using var topics = new TopicsDataTable(); - topics.AddRow(1, "Root", "Container", null, hasChildren: false); + topics.AddRow(1, "Root", "Container", hasChildren: false); using var tableReader = new DataTableReader(topics); @@ -579,7 +579,7 @@ public void LoadTopicGraph_WithHasChildrenAndLoadedChildren_ReturnsChildrenLoade using var topics = new TopicsDataTable(); - topics.AddRow(1, "Root", "Container", null, hasChildren: true); + topics.AddRow(1, "Root", "Container", hasChildren: true); topics.AddRow(2, "Child", "Page", 1, hasChildren: false); using var tableReader = new DataTableReader(topics); @@ -604,7 +604,7 @@ public void LoadTopicGraph_WithHasChildrenOnAncestorAndLoadedSubtree_SetsLoadSta using var topics = new TopicsDataTable(); - topics.AddRow(1, "Root", "Container", null, hasChildren: true); + topics.AddRow(1, "Root", "Container", hasChildren: true); topics.AddRow(2, "Child", "Container", 1, hasChildren: true); topics.AddRow(3, "Grandchild", "Page", 2, hasChildren: false); From 56379ac29914edd72cf4e2f13e1464b235850f72 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 7 Jul 2026 22:22:13 -0700 Subject: [PATCH 106/337] Prefer implicit constructors when type is known --- OnTopic.Tests/TopicRepositoryBaseTest.cs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/OnTopic.Tests/TopicRepositoryBaseTest.cs b/OnTopic.Tests/TopicRepositoryBaseTest.cs index 3f17a874..95a9cb4a 100644 --- a/OnTopic.Tests/TopicRepositoryBaseTest.cs +++ b/OnTopic.Tests/TopicRepositoryBaseTest.cs @@ -45,8 +45,8 @@ public class TopicRepositoryBaseTest { /// crawling the object graph. /// public TopicRepositoryBaseTest() { - _topicRepository = new StubTopicRepository(); - _cachedTopicRepository = new CachedTopicRepository(_topicRepository); + _topicRepository = new(); + _cachedTopicRepository = new(_topicRepository); } /*============================================================================================================================ From 45feabe4e3f4ff9c2589b1f3376eaaea1cb3df3d Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 7 Jul 2026 22:26:56 -0700 Subject: [PATCH 107/337] Fixed syntax errors with XML docblocks Still not clear if this is just a JetBrains Rider issue or a legitimate issue with how XML docblocks are parsed. Regardless, keeping quoted identifiers on the same line addresses the issue. Also removed some implicit values while I was at it. --- OnTopic.Tests/TopicRepositoryBaseTest.cs | 44 ++++++++++++------------ 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/OnTopic.Tests/TopicRepositoryBaseTest.cs b/OnTopic.Tests/TopicRepositoryBaseTest.cs index 95a9cb4a..bea0e4bd 100644 --- a/OnTopic.Tests/TopicRepositoryBaseTest.cs +++ b/OnTopic.Tests/TopicRepositoryBaseTest.cs @@ -144,8 +144,8 @@ public void Load_ValidDate_ReturnsTopic() { | TEST: ROLLBACK: TOPIC: UPDATES LAST MODIFIED \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Calls with a valid date and ensures that the value is updated. + /// Calls with a valid date and ensures that the value is updated. /// [Fact] public void Rollback_Topic_UpdatesLastModified() { @@ -246,7 +246,7 @@ public void Delete_Descendants_ThrowsException() { _ = new Topic("Child", "Page", topic); Assert.Throws(() => - _topicRepository.Delete(topic, false) + _topicRepository.Delete(topic) ); } @@ -283,7 +283,7 @@ public void Delete_NestedTopics_Succeeds() { var topic = new Topic("Topic", "Page", root); _ = new Topic("Child", "List", topic); - _topicRepository.Delete(topic, false); + _topicRepository.Delete(topic); Assert.Empty(root.Children); @@ -807,8 +807,8 @@ public void Save_IsRecursive_SavesChild() { \---------------------------------------------------------------------------------------------------------------------------*/ /// /// Saves a new with an unresolved and confirms that it successfully - /// resolves it by marking the collection as as false. + /// resolves it by marking the collection as as false. /// [Fact] public void Save_UnresolvedReference_Resolves() { @@ -990,8 +990,8 @@ public void Delete_AttributeDescriptor_UpdatesContentTypeCache() { | TEST: LOAD: TOPIC LOADED EVENT: IS RAISED \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Loads a topic using and ensures that the event is raised. + /// Loads a topic using and ensures that the + /// event is raised. /// [Fact] public void Load_TopicLoadedEvent_IsRaised() { @@ -1014,8 +1014,8 @@ public void Load_TopicLoadedEvent_IsRaised() { | TEST: LOAD: TOPIC LOADED EVENT: IS RAISED WITH VERSION \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Loads a topic using and ensures that the event is raised. + /// Loads a topic using and ensures that the event is raised. /// [Fact] public void Load_TopicLoadedEvent_IsRaisedWithVersion() { @@ -1042,8 +1042,8 @@ public void Load_TopicLoadedEvent_IsRaisedWithVersion() { | TEST: DELETE: TOPIC DELETED EVENT: IS RAISED \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Creates a and then immediately deletes it. Ensures that the event is raised. + /// Creates a and then immediately deletes it. Ensures that the event is raised. /// [Fact] public void Delete_TopicDeletedEvent_IsRaised() { @@ -1089,8 +1089,8 @@ public void Save_TopicSavedEvent_IsRaised() { | TEST: SAVE: TOPIC RENAMED EVENT: IS RAISED \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Creates a and then immediately saves it. Ensures that the event is raised. + /// Creates a and then immediately saves it. Ensures that the event is raised. /// [Fact] public void Save_TopicRenamedEvent_IsRaised() { @@ -1114,8 +1114,8 @@ public void Save_TopicRenamedEvent_IsRaised() { | TEST: SAVE: TOPIC MOVED EVENT: IS RAISED \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Creates a , changes its parent, and then saves it. Ensures that the event is raised. + /// Creates a , changes its parent, and then saves it. Ensures that the event is raised. /// [Fact] public void Save_TopicMovedEvent_IsRaised() { @@ -1274,8 +1274,8 @@ public void EnsureLoaded_ReferencesNotLoaded_MarksLoaded() { \---------------------------------------------------------------------------------------------------------------------------*/ /// /// Loads a , marks its as , then accesses - /// the getter. Verifies that the auto-load fires, promoting the boundary to via the 's fill. + /// the getter. Verifies that the auto-load fires, promoting the boundary to via the 's fill. /// [Fact] public void IsLoaded_ChildrenNotLoadedState_TriggersEnsureLoaded() { @@ -1314,8 +1314,8 @@ public void IsLoaded_ChildrenLoadedState_DoesNotCallResolver() { \---------------------------------------------------------------------------------------------------------------------------*/ /// /// Loads a whose has been manually set to and confirms that promotes the boundary to via the 's fill. + /// /> and confirms that promotes the boundary to via the 's fill. /// [Fact] public void EnsureLoaded_ChildrenNotLoaded_MarksLoaded() { @@ -1357,8 +1357,8 @@ public void Move_TopicMovedEvent_IsRaised() { | TEST: MOVE: SAME LOCATION: EVENT NOT RAISED \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Creates a and then moves it to the exact same location in the tree. Ensures that the event is not raised. + /// Creates a and then moves it to the exact same location in the tree. Ensures that the event is not raised. /// [Fact] public void Move_SameLocation_EventNotRaised() { From 7b56929a80e9ed403bb7c1bf9a6f57452d4b974a Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 7 Jul 2026 22:29:57 -0700 Subject: [PATCH 108/337] Avoid multiple enumeration via `ToList()` --- OnTopic.Tests/TopicRepositoryBaseTest.cs | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/OnTopic.Tests/TopicRepositoryBaseTest.cs b/OnTopic.Tests/TopicRepositoryBaseTest.cs index bea0e4bd..e0225508 100644 --- a/OnTopic.Tests/TopicRepositoryBaseTest.cs +++ b/OnTopic.Tests/TopicRepositoryBaseTest.cs @@ -3,7 +3,6 @@ | Client Ignia, LLC | Project Topics Library \=============================================================================================================================*/ -using OnTopic.Associations; using OnTopic.Collections.Specialized; using OnTopic.Data.Caching; using OnTopic.Metadata; @@ -374,7 +373,7 @@ public void GetAttributes_EmptyAttributes_Skips() { topic.Attributes.SetValue("EmptyAttribute", ""); topic.Attributes.SetValue("NullAttribute", null); - var attributes = _topicRepository.GetAttributesProxy(topic, null); + var attributes = _topicRepository.GetAttributesProxy(topic, null).ToList(); Assert.DoesNotContain(attributes, a => a.Key is "EmptyAttribute"); Assert.DoesNotContain(attributes, a => a.Key is "NullAttribute"); @@ -437,10 +436,10 @@ public void GetAttributes_ExtendedAttributeMismatch_ReturnsExtendedAttributes() topic.Attributes.SetValue("MetaTitle", "Metatitle", markDirty: false, isExtendedAttribute: null); topic.Attributes.SetValue("Arbitrary", "Value", markDirty: false, isExtendedAttribute: true); - var dirtyExtended = _topicRepository.GetAttributesProxy(topic, true, true); - var dirtyIndexed = _topicRepository.GetAttributesProxy(topic, false, true); - var cleanExtended = _topicRepository.GetAttributesProxy(topic, true, false); - var cleanIndexed = _topicRepository.GetAttributesProxy(topic, false, false); + var dirtyExtended = _topicRepository.GetAttributesProxy(topic, true, true).ToList(); + var dirtyIndexed = _topicRepository.GetAttributesProxy(topic, false, true).ToList(); + var cleanExtended = _topicRepository.GetAttributesProxy(topic, true, false).ToList(); + var cleanIndexed = _topicRepository.GetAttributesProxy(topic, false, false).ToList(); //Expect Title, even though it isn't IsDirty Assert.Single(dirtyExtended); @@ -537,7 +536,7 @@ public void GetAttributes_ArbitraryAttributeWithLongValue_ReturnsAsExtendedAttri var topic = new Topic("Test", "ContentTypes"); - topic.Attributes.SetValue("ArbitraryAttribute", new string('x', 256)); + topic.Attributes.SetValue("ArbitraryAttribute", new('x', 256)); var attributes = _topicRepository.GetAttributesProxy(topic, true); @@ -559,7 +558,7 @@ public void GetUnmatchedAttributes_ReturnsAttributes() { topic.Attributes.SetValue("Title", "Title"); - var attributes = _topicRepository.GetUnmatchedAttributesProxy(topic); + var attributes = _topicRepository.GetUnmatchedAttributesProxy(topic).ToList(); Assert.True(attributes.Any()); Assert.DoesNotContain(attributes, a => a.Key is "Title"); @@ -586,7 +585,7 @@ public void GetUnmatchedAttributes_EmptyArbitraryAttributes_ReturnsAttributes() topic.Attributes.SetValue("YetAnotherArbitraryAttribute", "Value"); topic.Attributes.SetValue("YetAnotherArbitraryAttribute", null); - var attributes = _topicRepository.GetUnmatchedAttributesProxy(topic); + var attributes = _topicRepository.GetUnmatchedAttributesProxy(topic).ToList(); Assert.Contains(attributes, a => a.Key is "ArbitraryAttribute"); Assert.Contains(attributes, a => a.Key is "YetAnotherArbitraryAttribute"); From a3b9a210addca23aca0c367f0d97d8270cdd52a8 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 7 Jul 2026 22:30:55 -0700 Subject: [PATCH 109/337] Prefer `Count` to `Any()` --- OnTopic.Tests/TopicRepositoryBaseTest.cs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/OnTopic.Tests/TopicRepositoryBaseTest.cs b/OnTopic.Tests/TopicRepositoryBaseTest.cs index e0225508..de10d7d5 100644 --- a/OnTopic.Tests/TopicRepositoryBaseTest.cs +++ b/OnTopic.Tests/TopicRepositoryBaseTest.cs @@ -560,7 +560,7 @@ public void GetUnmatchedAttributes_ReturnsAttributes() { var attributes = _topicRepository.GetUnmatchedAttributesProxy(topic).ToList(); - Assert.True(attributes.Any()); + Assert.True(attributes.Count != 0); Assert.DoesNotContain(attributes, a => a.Key is "Title"); } @@ -925,7 +925,7 @@ public void Move_ContentTypeDescriptor_UpdatesContentTypeCache() { _topicRepository.Move(contactContentType, pageContentType); - Assert.NotEqual(contactContentType?.AttributeDescriptors.Count, contactAttributeCount); + Assert.NotEqual(contactContentType.AttributeDescriptors.Count, contactAttributeCount); } From 3100cf6fb43005bd7d1f549265092dc81e829904 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 7 Jul 2026 22:34:05 -0700 Subject: [PATCH 110/337] Minor grammatical clean-up in XML docblocks --- OnTopic.Tests/TopicRepositoryBaseTest.cs | 67 ++++++++++++++++++++---- 1 file changed, 58 insertions(+), 9 deletions(-) diff --git a/OnTopic.Tests/TopicRepositoryBaseTest.cs b/OnTopic.Tests/TopicRepositoryBaseTest.cs index de10d7d5..439d1688 100644 --- a/OnTopic.Tests/TopicRepositoryBaseTest.cs +++ b/OnTopic.Tests/TopicRepositoryBaseTest.cs @@ -192,7 +192,7 @@ public void Load_OldDate_ThrowsException() => | TEST: DELETE: BASE TOPIC: THROWS EXCEPTION \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Deletes a topic which other topics, outside of the graph, derive from. Expects exception. + /// Deletes a topic which other topics, outside the graph, derive from. Expects exception. /// [Fact] public void Delete_BaseTopic_ThrowsException() { @@ -341,8 +341,8 @@ public void Delete_IncomingRelationships_DeleteAssociations() { | TEST: GET ATTRIBUTES: ANY ATTRIBUTES: RETURNS ALL ATTRIBUTES \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Retrieves a list of attributes from a topic, without any filtering by whether or not the attribute is an . + /// Retrieves a list of attributes from a topic, without any filtering by whether the attribute is an . /// [Fact] public void GetAttributes_AnyAttributes_ReturnsAllAttributes() { @@ -361,9 +361,9 @@ public void GetAttributes_AnyAttributes_ReturnsAllAttributes() { | TEST: GET ATTRIBUTES: EMPTY ATTRIBUTES: SKIPS \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Retrieves a list of attributes from a topic, without any filtering by whether or not the attribute is an . Any s with a null or empty value should - /// be skipped. + /// Retrieves a list of attributes from a topic, without any filtering by whether the attribute is an . Any s with a null or empty value should be + /// skipped. /// [Fact] public void GetAttributes_EmptyAttributes_Skips() { @@ -507,7 +507,7 @@ public void GetAttributes_ExcludeLastModified_ReturnsOtherAttributes() { \---------------------------------------------------------------------------------------------------------------------------*/ /// /// Sets an arbitrary (unmatched) attribute on a with a value shorter than 255 characters, then - /// ensures that it is returned as an an indexed when calling indexed when calling . /// [Fact] @@ -528,7 +528,7 @@ public void GetAttributes_ArbitraryAttributeWithShortValue_ReturnsAsIndexedAttri \---------------------------------------------------------------------------------------------------------------------------*/ /// /// Sets an arbitrary (unmatched) attribute on a with a value longer than 255 characters, then - /// ensures that it is returned as an an when calling when calling . /// [Fact] @@ -1273,7 +1273,7 @@ public void EnsureLoaded_ReferencesNotLoaded_MarksLoaded() { \---------------------------------------------------------------------------------------------------------------------------*/ /// /// Loads a , marks its as , then accesses - /// the getter. Verifies that the auto-load fires, promoting the boundary to getter. Verifies that the autoload fires, promoting the boundary to via the 's fill. /// [Fact] @@ -1352,6 +1352,55 @@ public void Move_TopicMovedEvent_IsRaised() { } + /*============================================================================================================================ + | TEST: ENSURE LOADED: WITH MISSING RELATIONSHIP TARGET: RESOLVES AND CONNECTS + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Calls on a topic whose Relationships.LoadState is NotLoaded, + /// confirming that the resolver re-queries for the topic's relationships, loads any missing targets, and connects the + /// edges. + /// + /// + /// The stub pre-seeds a relationship from the root topic to Root:Web (id 10000). The cache is initialized with only the + /// root topic, so the relationship target is initially absent. EnsureLoaded is expected to load it and connect the + /// edge through the full resolver stack. + /// + [Fact] + public void EnsureLoaded_WithMissingRelationshipTarget_ResolvesAndConnects() { + + // Get the root topic from cache; seed a deferred entry to simulate a pending relationship target + var source = _cachedTopicRepository.Load(-1)!; + source.Relationships.Deferred.Add(new("_stub", 11111)); + + // Act: EnsureLoaded re-queries, finds the missing target, loads it, and connects the edge + _cachedTopicRepository.EnsureLoaded(source, TopicPayload.Relationships); + + // Relationships are now Loaded and any pre-seeded edges are connected + Assert.Equal(LoadState.Loaded, source.Relationships.LoadState); + + } + + /*============================================================================================================================ + | TEST: ENSURE LOADED: RELATIONSHIPS: ALREADY LOADED: SKIPS FILL + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Calls on a topic whose relationships are already and confirms it returns immediately without re-querying. + /// + [Fact] + public void EnsureLoaded_Relationships_AlreadyLoaded_SkipsFill() { + + // Get the root topic; relationships start as Loaded (Deferred is empty) after initialization + var source = _cachedTopicRepository.Load(-1)!; + + // Act + _cachedTopicRepository.EnsureLoaded(source, TopicPayload.Relationships); + + // LoadState is unchanged; no fill was triggered + Assert.Equal(LoadState.Loaded, source.Relationships.LoadState); + + } + /*============================================================================================================================ | TEST: MOVE: SAME LOCATION: EVENT NOT RAISED \---------------------------------------------------------------------------------------------------------------------------*/ From e2b8f75a3d04d1a37c7acc8fb88a00a4ae21b095 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Wed, 8 Jul 2026 14:03:48 -0700 Subject: [PATCH 111/337] Unit tests for dynamic loading associations These pertain to #111. --- OnTopic.Tests/SqlTopicRepositoryTest.cs | 62 ++++++++++++++++++ OnTopic.Tests/TopicRepositoryBaseTest.cs | 80 ++++++++++++++++++++++++ 2 files changed, 142 insertions(+) diff --git a/OnTopic.Tests/SqlTopicRepositoryTest.cs b/OnTopic.Tests/SqlTopicRepositoryTest.cs index b22587cd..bd79da21 100644 --- a/OnTopic.Tests/SqlTopicRepositoryTest.cs +++ b/OnTopic.Tests/SqlTopicRepositoryTest.cs @@ -342,6 +342,10 @@ public void LoadTopicGraph_WithDeletedRelationship_RemovesRelationship() { /// deferred via HasExtendedAttributes = true) with a relationship whose target is resident, and confirms that /// returns . /// + /// + /// Confirms that the relationship result set is still returned and is correctly established even + /// when extended attributes are deferred. + /// [Fact] public void LoadTopicGraph_IndexedOnlyWithRelationship_ReturnsLoaded() { @@ -370,6 +374,10 @@ public void LoadTopicGraph_IndexedOnlyWithRelationship_ReturnsLoaded() { /// non-resident, and confirms that returns . /// + /// + /// LoadState.NotLoaded blocks DeleteUnmatched on save; the missing edge is reconnected when the outer + /// resolver calls EnsureLoaded(Relationships) for the topic. + /// [Fact] public void LoadTopicGraph_IndexedOnlyWithMissingRelationship_ReturnsNotLoaded() { @@ -443,6 +451,60 @@ public void LoadTopicGraph_IndexedOnlyWithMissingReference_ReturnsNotLoaded() { } + /*============================================================================================================================ + | TEST: LOAD TOPIC GRAPH: WITH MISSING RELATIONSHIP: SETS NOT LOADED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Calls with a relationship whose target is not in the live graph, + /// and confirms that is set to to + /// block DeleteUnmatched on save until the edge is resolved via EnsureLoaded. + /// + [Fact] + public void LoadTopicGraph_WithMissingRelationship_SetsNotLoaded() { + + using var topics = new TopicsDataTable(); + using var empty = new AttributesDataTable(); + using var relationships = new RelationshipsDataTable(); + + topics.AddRow(1, "Root", "Container"); + relationships.AddRow(1, "Test", 99, false); + + using var tableReader = new DataTableReader([topics, empty, empty, relationships]); + + var topic = tableReader.LoadTopicGraph(); + + Assert.NotNull(topic); + Assert.False(topic.IsLoaded(TopicPayload.Relationships)); + + } + + /*============================================================================================================================ + | TEST: LOAD TOPIC GRAPH: WITH MISSING REFERENCE: SETS NOT LOADED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Calls with a reference whose target is not in the live graph, and + /// confirms that is set to to block + /// DeleteUnmatched on save until the reference is resolved via EnsureLoaded. + /// + [Fact] + public void LoadTopicGraph_WithMissingReference_SetsNotLoaded() { + + using var topics = new TopicsDataTable(); + using var empty = new AttributesDataTable(); + using var references = new TopicReferencesDataTable(); + + topics.AddRow(1, "Root", "Container"); + references.AddRow(1, "Test", 99); + + using var tableReader = new DataTableReader([topics, empty, empty, empty, references]); + + var topic = tableReader.LoadTopicGraph(); + + Assert.NotNull(topic); + Assert.False(topic.IsLoaded(TopicPayload.References)); + + } + /*============================================================================================================================ | TEST: LOAD TOPIC GRAPH: WITH VERSION HISTORY: RETURNS VERSIONS \---------------------------------------------------------------------------------------------------------------------------*/ diff --git a/OnTopic.Tests/TopicRepositoryBaseTest.cs b/OnTopic.Tests/TopicRepositoryBaseTest.cs index 439d1688..3f3719ef 100644 --- a/OnTopic.Tests/TopicRepositoryBaseTest.cs +++ b/OnTopic.Tests/TopicRepositoryBaseTest.cs @@ -1308,6 +1308,86 @@ public void IsLoaded_ChildrenLoadedState_DoesNotCallResolver() { } + /*============================================================================================================================ + | TEST: IS LOADED: RELATIONSHIPS NOT LOADED STATE: TRIGGERS ENSURE LOADED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Loads a , marks its as , then + /// accesses the getter. Verifies that the autoload fires, promoting the boundary to + /// via the 's fill. + /// + [Fact] + public void IsLoaded_RelationshipsNotLoadedState_TriggersEnsureLoaded() { + + var topic = _topicRepository.Load(11111); + + topic!.Relationships.Deferred.Add(new("_stub", 11111)); + _ = topic.Relationships; + + Assert.True(topic.IsLoaded(TopicPayload.Relationships)); + + } + + /*============================================================================================================================ + | TEST: IS LOADED: RELATIONSHIPS LOADED STATE: DOES NOT CALL RESOLVER + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Loads a whose is already and + /// accesses the getter. Verifies that the boundary stays without the resolver being called + /// redundantly. + /// + [Fact] + public void IsLoaded_RelationshipsLoadedState_DoesNotCallResolver() { + + var topic = _topicRepository.Load(11111); + + Assert.True(topic!.IsLoaded(TopicPayload.Relationships)); + _ = topic.Relationships; + + Assert.True(topic.IsLoaded(TopicPayload.Relationships)); + + } + + /*============================================================================================================================ + | TEST: IS LOADED: REFERENCES NOT LOADED STATE: TRIGGERS ENSURE LOADED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Loads a , marks its as , then + /// accesses the getter. Verifies that the autoload fires, promoting the boundary to + /// via the 's fill. + /// + [Fact] + public void IsLoaded_ReferencesNotLoadedState_TriggersEnsureLoaded() { + + var topic = _topicRepository.Load(11111); + + topic!.References.Deferred.Add(new("_stub", 11111)); + _ = topic.References; + + Assert.True(topic.IsLoaded(TopicPayload.References)); + + } + + /*============================================================================================================================ + | TEST: IS LOADED: REFERENCES LOADED STATE: DOES NOT CALL RESOLVER + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Loads a whose is already and accesses + /// the getter. Verifies that the boundary stays without the resolver being called + /// redundantly. + /// + [Fact] + public void IsLoaded_ReferencesLoadedState_DoesNotCallResolver() { + + var topic = _topicRepository.Load(11111); + + Assert.True(topic!.IsLoaded(TopicPayload.References)); + _ = topic.References; + + Assert.True(topic.IsLoaded(TopicPayload.References)); + + } + /*============================================================================================================================ | TEST: IS LOADED: CHILDREN NOT LOADED: MARKS LOADED \---------------------------------------------------------------------------------------------------------------------------*/ From a3b73602a108a438fb6ebdc0a0046630f811eb1b Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Wed, 8 Jul 2026 16:27:34 -0700 Subject: [PATCH 112/337] Move `Load()`, `EnsureLoaded()` to be `async` This is a massive architectural shift and, obviously, a breaking change, but a) allows the lazy-loading (#111) of associations to happen in parallel, and b) will support migrating to .NET built-in dependency injection and, thus, taking advantage of its support for asynchronous loading, which isn't supported by the activator model today. This also required moving `EnsureLoaded()` to async only, and thus removing the original `EnsureLoaded()` and replacing it with the `EnsureLoadedAsync()`. A number of these cases still require `GetAwaiter().GetResult()`, which is unfortunately, though quite a few of those will be resolved in subsequent commits. One case that will be persisted is the synchronous lazy-loading when calling lazy-loading properties (#111) directly. That said, typically we're working through the `TopicMappingService` and, thus, the hope is that we can forecast those calls and asynchronously load them before the `TopicMappingService` gets that far. This also required rehoming the `SqlDataReaderExtensions` off of `DbDataReader` instead of the `IDataReader`. That's an unfortunate compromise, but needed to permit asynchronous operation. --- .../SampleActivator.cs | 2 +- .../Repositories/StubTopicRepository.cs | 15 +- .../SampleActivator.cs | 2 +- .../TestDoubles/TestTopicRepository.cs | 6 +- .../TopicControllerTest.cs | 2 +- .../TopicRepositoryExtensionsTest.cs | 4 +- .../TopicViewComponentTest.cs | 2 +- .../Components/MenuViewComponentBase{T}.cs | 2 +- .../Controllers/ErrorController.cs | 6 +- .../Controllers/RedirectController.cs | 2 +- .../Controllers/SitemapController.cs | 2 +- .../TopicRepositoryExtensions.cs | 2 +- .../_filters/TopicResponseCacheAttribute.cs | 2 +- OnTopic.Data.Caching/CachedTopicRepository.cs | 76 +++------ OnTopic.Data.Sql/Properties/AssemblyInfo.cs | 1 + OnTopic.Data.Sql/SqlDataReaderExtensions.cs | 37 ++--- OnTopic.Data.Sql/SqlTopicRepository.cs | 144 ++---------------- OnTopic.TestDoubles/DummyTopicRepository.cs | 12 +- OnTopic.TestDoubles/StubTopicRepository.cs | 22 ++- .../HierarchicalTopicMappingServiceTest.cs | 10 +- OnTopic.Tests/ITopicRepositoryTest.cs | 10 +- .../ReverseTopicMappingServiceTest.cs | 6 +- OnTopic.Tests/SqlTopicRepositoryTest.cs | 48 +++--- .../TestDoubles/TrackingTopicLoadResolver.cs | 15 +- OnTopic.Tests/TopicMappingServiceTest.cs | 10 +- OnTopic.Tests/TopicQueryingTest.cs | 6 +- OnTopic.Tests/TopicRepositoryBaseTest.cs | 68 ++++----- .../HierarchicalTopicMappingService{T}.cs | 2 +- .../Reverse/ReverseTopicMappingService.cs | 12 +- OnTopic/Mapping/TopicMappingService.cs | 10 +- OnTopic/Repositories/ITopicLoadResolver.cs | 5 +- OnTopic/Repositories/ITopicRepository.cs | 12 +- .../Repositories/ObservableTopicRepository.cs | 12 +- OnTopic/Repositories/TopicRepository.cs | 4 +- .../Repositories/TopicRepositoryDecorator.cs | 10 +- OnTopic/Topic.cs | 48 ++---- 36 files changed, 219 insertions(+), 410 deletions(-) diff --git a/OnTopic.AspNetCore.Mvc.Host/SampleActivator.cs b/OnTopic.AspNetCore.Mvc.Host/SampleActivator.cs index a61a0752..4657d71d 100644 --- a/OnTopic.AspNetCore.Mvc.Host/SampleActivator.cs +++ b/OnTopic.AspNetCore.Mvc.Host/SampleActivator.cs @@ -111,7 +111,7 @@ public object Create(ControllerContext context) { \-------------------------------------------------------------------------------------------------------------------------*/ if (DateTime.UtcNow > _cacheLastUpdated.AddMinutes(1)) { var currentUpdate = DateTime.UtcNow; - _topicRepository.Refresh(_topicRepository.Load()!, _cacheLastUpdated); + _topicRepository.Refresh(_topicRepository.Load().GetAwaiter().GetResult()!, _cacheLastUpdated); _cacheLastUpdated = currentUpdate; } diff --git a/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/Repositories/StubTopicRepository.cs b/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/Repositories/StubTopicRepository.cs index 7bffae43..a9781add 100644 --- a/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/Repositories/StubTopicRepository.cs +++ b/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/Repositories/StubTopicRepository.cs @@ -42,18 +42,17 @@ public StubTopicRepository() : base() { | METHOD: LOAD \---------------------------------------------------------------------------------------------------------------------------*/ /// - public override Topic? Load( + public override Task Load( int topicId, Topic? referenceTopic = null, bool isRecursive = true, TopicPayload payload = TopicPayload.All ) { - /*-------------------------------------------------------------------------------------------------------------------------- | Lookup by TopicId \-------------------------------------------------------------------------------------------------------------------------*/ - var topic = _cache; + var topic = (Topic?)_cache; if (topicId > 0) { topic = _cache.FindFirst(t => t.Id.Equals(topicId)); @@ -69,12 +68,12 @@ public StubTopicRepository() : base() { /*-------------------------------------------------------------------------------------------------------------------------- | Return value \-------------------------------------------------------------------------------------------------------------------------*/ - return topic; + return Task.FromResult(topic); } /// - public override Topic? Load( + public override Task Load( string uniqueKey, Topic? referenceTopic = null, bool isRecursive = true, @@ -85,7 +84,7 @@ public StubTopicRepository() : base() { | Validate parameters \-------------------------------------------------------------------------------------------------------------------------*/ if (String.IsNullOrEmpty(uniqueKey)) { - return null; + return Task.FromResult(null); } /*-------------------------------------------------------------------------------------------------------------------------- @@ -103,12 +102,12 @@ public StubTopicRepository() : base() { /*-------------------------------------------------------------------------------------------------------------------------- | Return topic \-------------------------------------------------------------------------------------------------------------------------*/ - return topic; + return Task.FromResult(topic); } /// - public override Topic? Load(int topicId, DateTime version, Topic? referenceTopic = null) => + public override Task Load(int topicId, DateTime version, Topic? referenceTopic = null) => throw new NotImplementedException(); /*============================================================================================================================ diff --git a/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/SampleActivator.cs b/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/SampleActivator.cs index 93e19bff..ec43e766 100644 --- a/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/SampleActivator.cs +++ b/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/SampleActivator.cs @@ -65,7 +65,7 @@ public SampleActivator() { _topicRepository = cachedTopicRepository; _typeLookupService = new DynamicTopicViewModelLookupService(); _topicMappingService = new TopicMappingService(_topicRepository, _typeLookupService); - _ = _topicRepository.Load(); + _ = _topicRepository.Load().GetAwaiter().GetResult(); /*-------------------------------------------------------------------------------------------------------------------------- | Establish hierarchical topic mapping service diff --git a/OnTopic.AspNetCore.Mvc.Tests/TestDoubles/TestTopicRepository.cs b/OnTopic.AspNetCore.Mvc.Tests/TestDoubles/TestTopicRepository.cs index 954fac2d..17937b95 100644 --- a/OnTopic.AspNetCore.Mvc.Tests/TestDoubles/TestTopicRepository.cs +++ b/OnTopic.AspNetCore.Mvc.Tests/TestDoubles/TestTopicRepository.cs @@ -43,15 +43,15 @@ public TestTopicRepository() : base() { | METHOD: LOAD \---------------------------------------------------------------------------------------------------------------------------*/ /// - public override Topic? Load() => _cache; + public override Task Load() => Task.FromResult(_cache); /// - public override Topic? Load( + public override Task Load( string uniqueKey, Topic? referenceTopic = null, bool isRecursive = true, TopicPayload payload = TopicPayload.All - ) => String.IsNullOrEmpty(uniqueKey)? null : _cache.FindFirst(t => t.GetUniqueKey() == uniqueKey); + ) => Task.FromResult(String.IsNullOrEmpty(uniqueKey)? null : _cache.FindFirst(t => t.GetUniqueKey() == uniqueKey)); /*============================================================================================================================ | METHOD: CREATE FAKE DATA diff --git a/OnTopic.AspNetCore.Mvc.Tests/TopicControllerTest.cs b/OnTopic.AspNetCore.Mvc.Tests/TopicControllerTest.cs index abf06f6c..d8a977c1 100644 --- a/OnTopic.AspNetCore.Mvc.Tests/TopicControllerTest.cs +++ b/OnTopic.AspNetCore.Mvc.Tests/TopicControllerTest.cs @@ -51,7 +51,7 @@ public TopicControllerTest(TestTopicRepository topicRepository) { | Establish dependencies \-------------------------------------------------------------------------------------------------------------------------*/ _topicRepository = new CachedTopicRepository(topicRepository); - _topic = _topicRepository.Load("Root:Web:Valid:Child")!; + _topic = _topicRepository.Load("Root:Web:Valid:Child").GetAwaiter().GetResult()!; _topicMappingService = new TopicMappingService(_topicRepository, new TopicViewModelLookupService()); _context = FakeControllerContext.GetControllerContext("Web", "Web/Valid/Child/"); diff --git a/OnTopic.AspNetCore.Mvc.Tests/TopicRepositoryExtensionsTest.cs b/OnTopic.AspNetCore.Mvc.Tests/TopicRepositoryExtensionsTest.cs index 0f302fcd..22ad2e47 100644 --- a/OnTopic.AspNetCore.Mvc.Tests/TopicRepositoryExtensionsTest.cs +++ b/OnTopic.AspNetCore.Mvc.Tests/TopicRepositoryExtensionsTest.cs @@ -51,7 +51,7 @@ public TopicRepositoryExtensionsTest(StubTopicRepository topicRepository) { public void Load_ByRoute_ReturnsTopic() { var routes = new RouteData(); - var topic = _topicRepository.Load("Root:Web:Web_0:Web_0_1:Web_0_1_1"); + var topic = _topicRepository.Load("Root:Web:Web_0:Web_0_1:Web_0_1_1").GetAwaiter().GetResult(); routes.Values.Add("rootTopic", "Web"); routes.Values.Add("path", "Web_0/Web_0_1/Web_0_1_1"); @@ -74,7 +74,7 @@ public void Load_ByRoute_ReturnsTopic() { public void Load_ByRoute_ReturnsRootTopic() { var routes = new RouteData(); - var topic = _topicRepository.Load("Root"); + var topic = _topicRepository.Load("Root").GetAwaiter().GetResult(); routes.Values.Add("path", "Root/"); diff --git a/OnTopic.AspNetCore.Mvc.Tests/TopicViewComponentTest.cs b/OnTopic.AspNetCore.Mvc.Tests/TopicViewComponentTest.cs index d45e9c97..55aca248 100644 --- a/OnTopic.AspNetCore.Mvc.Tests/TopicViewComponentTest.cs +++ b/OnTopic.AspNetCore.Mvc.Tests/TopicViewComponentTest.cs @@ -61,7 +61,7 @@ public TopicViewComponentTest(StubTopicRepository topicRepository) { | Establish dependencies \-------------------------------------------------------------------------------------------------------------------------*/ _topicRepository = new CachedTopicRepository(topicRepository); - _topic = _topicRepository.Load("Root:Web:Web_3:Web_3_0")!; + _topic = _topicRepository.Load("Root:Web:Web_3:Web_3_0").GetAwaiter().GetResult()!; _topicMappingService = new TopicMappingService(_topicRepository, new TopicViewModelLookupService()); /*-------------------------------------------------------------------------------------------------------------------------- diff --git a/OnTopic.AspNetCore.Mvc/Components/MenuViewComponentBase{T}.cs b/OnTopic.AspNetCore.Mvc/Components/MenuViewComponentBase{T}.cs index 6e9cc422..e47c50ea 100644 --- a/OnTopic.AspNetCore.Mvc/Components/MenuViewComponentBase{T}.cs +++ b/OnTopic.AspNetCore.Mvc/Components/MenuViewComponentBase{T}.cs @@ -82,7 +82,7 @@ IHierarchicalTopicMappingService hierarchicalTopicMappingService var configuredRoot = CurrentTopic.Attributes.GetValue("NavigationRoot", true); if (!String.IsNullOrEmpty(configuredRoot)) { - navigationRootTopic = TopicRepository.Load("Root:" + configuredRoot, CurrentTopic); + navigationRootTopic = TopicRepository.Load("Root:" + configuredRoot, CurrentTopic).GetAwaiter().GetResult(); } navigationRootTopic ??= HierarchicalTopicMappingService.GetHierarchicalRoot(CurrentTopic, 2, "Web"); diff --git a/OnTopic.AspNetCore.Mvc/Controllers/ErrorController.cs b/OnTopic.AspNetCore.Mvc/Controllers/ErrorController.cs index 3cb9a557..eec76489 100644 --- a/OnTopic.AspNetCore.Mvc/Controllers/ErrorController.cs +++ b/OnTopic.AspNetCore.Mvc/Controllers/ErrorController.cs @@ -69,9 +69,9 @@ public async virtual Task HttpAsync([FromRoute(Name="id")] int st /*-------------------------------------------------------------------------------------------------------------------------- | Identify relevant topic \-------------------------------------------------------------------------------------------------------------------------*/ - CurrentTopic = TopicRepository.Load($"{rootTopic}:{statusCode}")?? - TopicRepository.Load($"{rootTopic}:{statusCode/100*100}")?? - TopicRepository.Load($"{rootTopic}"); + CurrentTopic = await TopicRepository.Load($"{rootTopic}:{statusCode}").ConfigureAwait(false) + ?? await TopicRepository.Load($"{rootTopic}:{statusCode/100*100}").ConfigureAwait(false) + ?? await TopicRepository.Load($"{rootTopic}").ConfigureAwait(false); /*-------------------------------------------------------------------------------------------------------------------------- | Return topic view diff --git a/OnTopic.AspNetCore.Mvc/Controllers/RedirectController.cs b/OnTopic.AspNetCore.Mvc/Controllers/RedirectController.cs index 593ac5e9..cae43430 100644 --- a/OnTopic.AspNetCore.Mvc/Controllers/RedirectController.cs +++ b/OnTopic.AspNetCore.Mvc/Controllers/RedirectController.cs @@ -41,7 +41,7 @@ public ActionResult Redirect(int topicId) { /*-------------------------------------------------------------------------------------------------------------------------- | Find the topic with the correct PageID. \-------------------------------------------------------------------------------------------------------------------------*/ - var topic = _topicRepository.Load(topicId); + var topic = _topicRepository.Load(topicId).GetAwaiter().GetResult(); /*-------------------------------------------------------------------------------------------------------------------------- | Provide error handling diff --git a/OnTopic.AspNetCore.Mvc/Controllers/SitemapController.cs b/OnTopic.AspNetCore.Mvc/Controllers/SitemapController.cs index f055fcfd..4acbb9de 100644 --- a/OnTopic.AspNetCore.Mvc/Controllers/SitemapController.cs +++ b/OnTopic.AspNetCore.Mvc/Controllers/SitemapController.cs @@ -101,7 +101,7 @@ public ActionResult Index(bool indent = false, bool includeMetadata = false) { /*-------------------------------------------------------------------------------------------------------------------------- | Ensure topics are loaded \-------------------------------------------------------------------------------------------------------------------------*/ - var rootTopic = _topicRepository.Load(); + var rootTopic = _topicRepository.Load().GetAwaiter().GetResult(); Contract.Assume( rootTopic, diff --git a/OnTopic.AspNetCore.Mvc/TopicRepositoryExtensions.cs b/OnTopic.AspNetCore.Mvc/TopicRepositoryExtensions.cs index 72793089..353e7a0e 100644 --- a/OnTopic.AspNetCore.Mvc/TopicRepositoryExtensions.cs +++ b/OnTopic.AspNetCore.Mvc/TopicRepositoryExtensions.cs @@ -76,7 +76,7 @@ RouteData routeData if (topic is not null) break; if (String.IsNullOrEmpty(searchPath)) continue; try { - topic = topicRepository.Load(searchPath); + topic = topicRepository.Load(searchPath).GetAwaiter().GetResult(); } catch (InvalidKeyException) { //As route data comes from user-submitted requests, it's expected that some may contain invalid keys. From this diff --git a/OnTopic.AspNetCore.Mvc/_filters/TopicResponseCacheAttribute.cs b/OnTopic.AspNetCore.Mvc/_filters/TopicResponseCacheAttribute.cs index 4a39cfc7..ff5b15e5 100644 --- a/OnTopic.AspNetCore.Mvc/_filters/TopicResponseCacheAttribute.cs +++ b/OnTopic.AspNetCore.Mvc/_filters/TopicResponseCacheAttribute.cs @@ -73,7 +73,7 @@ public override void OnActionExecuting(ActionExecutingContext context) { \-------------------------------------------------------------------------------------------------------------------------*/ // Lookup the default cache profile for reference - _defaultCacheProfile ??= controller.TopicRepository.Load("Configuration:CacheProfiles:Default"); + _defaultCacheProfile ??= controller.TopicRepository.Load("Configuration:CacheProfiles:Default").GetAwaiter().GetResult(); // Ensure the above lookup is only performed once per application _defaultCacheProfile ??= new Topic("ImplicitDefault", "CacheProfile"); diff --git a/OnTopic.Data.Caching/CachedTopicRepository.cs b/OnTopic.Data.Caching/CachedTopicRepository.cs index a9c2c3dc..596ab042 100644 --- a/OnTopic.Data.Caching/CachedTopicRepository.cs +++ b/OnTopic.Data.Caching/CachedTopicRepository.cs @@ -49,7 +49,8 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos /*-------------------------------------------------------------------------------------------------------------------------- | Seed root topic (without descendants) \-------------------------------------------------------------------------------------------------------------------------*/ - var rootTopic = TopicRepository.Load("Root", referenceTopic: null, isRecursive: false); + var rootTopic = TopicRepository.Load("Root", referenceTopic: null, isRecursive: false) + .GetAwaiter().GetResult(); Contract.Assume( rootTopic, @@ -65,7 +66,8 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos /*-------------------------------------------------------------------------------------------------------------------------- | Eager-load Root:Configuration subtree (required for content-type descriptor resolution) \-------------------------------------------------------------------------------------------------------------------------*/ - TopicRepository.Load("Root:Configuration", referenceTopic: _cache, isRecursive: true, payload: TopicPayload.All); + TopicRepository.Load("Root:Configuration", referenceTopic: _cache, isRecursive: true, payload: TopicPayload.All) + .GetAwaiter().GetResult(); /*-------------------------------------------------------------------------------------------------------------------------- | Populate flat index from seeded topics @@ -91,7 +93,7 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos /// Missing IDs are recorded to prevent /// redundant round-trips for topics that genuinely do not exist. /// - public override Topic? Load( + public override async Task Load( int topicId, Topic? referenceTopic = null, bool isRecursive = true, @@ -126,7 +128,8 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos /*-------------------------------------------------------------------------------------------------------------------------- | On miss: Load with ancestors and merge result into the live graph \-------------------------------------------------------------------------------------------------------------------------*/ - var loaded = TopicRepository.Load(topicId, referenceTopic: null, isRecursive: false); + var loaded = await TopicRepository.Load(topicId, referenceTopic: null, isRecursive: false) + .ConfigureAwait(false); // If it's missing, populate the appropriate index so we don't try loading it again if (loaded is null) { @@ -154,7 +157,7 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos /// Missing IDs are recorded to prevent /// redundant round-trips for topics that genuinely do not exist. /// - public override Topic? Load( + public override async Task Load( string uniqueKey, Topic? referenceTopic = null, bool isRecursive = true, @@ -199,7 +202,8 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos /*-------------------------------------------------------------------------------------------------------------------------- | On miss: Load with ancestors and merge result into the live graph \-------------------------------------------------------------------------------------------------------------------------*/ - var loaded = TopicRepository.Load(uniqueKey, referenceTopic: null, isRecursive: false); + var loaded = await TopicRepository.Load(uniqueKey, referenceTopic: null, isRecursive: false) + .ConfigureAwait(false); if (loaded is null) { lock (_syncLock) { @@ -219,7 +223,7 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos } /// - public override Topic? Load(int topicId, DateTime version, Topic? referenceTopic = null) { + public override async Task Load(int topicId, DateTime version, Topic? referenceTopic = null) { /*-------------------------------------------------------------------------------------------------------------------------- | Normalize parameters @@ -238,7 +242,8 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos /*-------------------------------------------------------------------------------------------------------------------------- | Return appropriate topic \-------------------------------------------------------------------------------------------------------------------------*/ - var topic = TopicRepository.Load(topicId, version, referenceTopic?? _cache); + var topic = await TopicRepository.Load(topicId, version, referenceTopic ?? _cache) + .ConfigureAwait(false); StampResolver(topic); return topic; @@ -249,46 +254,7 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos \---------------------------------------------------------------------------------------------------------------------------*/ /// - public virtual void EnsureLoaded(Topic topic, TopicPayload payload) { - - /*-------------------------------------------------------------------------------------------------------------------------- - | Validate parameters - \-------------------------------------------------------------------------------------------------------------------------*/ - Contract.Requires(topic); - - /*-------------------------------------------------------------------------------------------------------------------------- - | Filter to pending (i.e. not yet Loaded) payload - \-------------------------------------------------------------------------------------------------------------------------*/ - payload = topic.FilterPayload(payload); - - if (payload is TopicPayload.None) { - return; - } - - /*-------------------------------------------------------------------------------------------------------------------------- - | Delegate to the inner resolver; captures missing targets in the Deferred collections - \-------------------------------------------------------------------------------------------------------------------------*/ - if (TopicRepository is ITopicLoadResolver resolver) { - resolver.EnsureLoaded(topic, payload); - } - - // Resolve any deferred relationship/reference targets through the cache layer - ResolveDeferredAssociations(topic, payload); - - // Update flat index and stamp resolver for any newly loaded children - if (payload.HasFlag(TopicPayload.Children)) { - lock (_syncLock) { - foreach (var child in topic.Children) { - IndexTopic(child); - } - } - StampResolver(topic); - } - - } - - /// - public virtual Task EnsureLoadedAsync(Topic topic, TopicPayload payload, CancellationToken cancellationToken) { + public virtual async Task EnsureLoaded(Topic topic, TopicPayload payload, CancellationToken cancellationToken = default) { /*-------------------------------------------------------------------------------------------------------------------------- | Validate parameters @@ -301,18 +267,18 @@ public virtual Task EnsureLoadedAsync(Topic topic, TopicPayload payload, Cancell payload = topic.FilterPayload(payload); if (payload is TopicPayload.None) { - return Task.CompletedTask; + return; } /*-------------------------------------------------------------------------------------------------------------------------- | Delegate to the inner resolver; captures missing targets in the Deferred collections \-------------------------------------------------------------------------------------------------------------------------*/ if (TopicRepository is ITopicLoadResolver resolver) { - resolver.EnsureLoaded(topic, payload); + await resolver.EnsureLoaded(topic, payload, cancellationToken).ConfigureAwait(false); } // Resolve any deferred relationship/reference targets through the cache layer - ResolveDeferredAssociations(topic, payload); + await ResolveDeferredAssociations(topic, payload, cancellationToken).ConfigureAwait(false); // Update flat index and stamp resolver for any newly loaded children if (payload.HasFlag(TopicPayload.Children)) { @@ -324,8 +290,6 @@ public virtual Task EnsureLoadedAsync(Topic topic, TopicPayload payload, Cancell StampResolver(topic); } - return Task.CompletedTask; - } /*============================================================================================================================ @@ -438,14 +402,14 @@ protected override void OnTopicRenamed(TopicRenameEventArgs args) { /// The payload flags that were requested; only and are acted upon. /// - private void ResolveDeferredAssociations(Topic topic, TopicPayload payload) { + private async Task ResolveDeferredAssociations(Topic topic, TopicPayload payload, CancellationToken cancellationToken) { var rawTopic = (ITopicBackingAccessor)topic; // Resolve deferred relationship targets; unresolvable targets are treated as stale and discarded if (payload.HasFlag(TopicPayload.Relationships) && rawTopic.Relationships.Deferred.Count > 0) { foreach (var deferred in rawTopic.Relationships.Deferred.ToArray()) { - var target = Load(deferred.TopicId); + var target = await Load(deferred.TopicId).ConfigureAwait(false); // SetValue removes the matching Deferred entry; stale entries are cleared by the Topic getter if (target is not null) { rawTopic.Relationships.SetValue(deferred.Key, target, markDirty: false); @@ -456,7 +420,7 @@ private void ResolveDeferredAssociations(Topic topic, TopicPayload payload) { // Resolve deferred reference targets; unresolvable targets are treated as stale and discarded if (payload.HasFlag(TopicPayload.References) && rawTopic.References.Deferred.Count > 0) { foreach (var deferred in rawTopic.References.Deferred.ToArray()) { - var target = Load(deferred.TopicId); + var target = await Load(deferred.TopicId).ConfigureAwait(false); // SetValue removes the matching Deferred entry; stale entries are cleared by the Topic getter if (target is not null) { rawTopic.References.SetValue(deferred.Key, target, markDirty: false); diff --git a/OnTopic.Data.Sql/Properties/AssemblyInfo.cs b/OnTopic.Data.Sql/Properties/AssemblyInfo.cs index e314ced8..f3124e72 100644 --- a/OnTopic.Data.Sql/Properties/AssemblyInfo.cs +++ b/OnTopic.Data.Sql/Properties/AssemblyInfo.cs @@ -8,6 +8,7 @@ | USING DIRECTIVES (GLOBAL) \-----------------------------------------------------------------------------------------------------------------------------*/ global using System.Data; +global using System.Data.Common; global using Microsoft.Data.SqlClient; global using OnTopic.Internal.Diagnostics; diff --git a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs index 5f45aa5c..f941c7f6 100644 --- a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs +++ b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs @@ -57,18 +57,21 @@ internal static class SqlDataReaderExtensions { /// cref="Topic.BaseTopic"/>. This is useful for cases where it's known that a shallow copy is being retrieved, and /// thus external references aren't likely to be available. /// - internal static Topic? LoadTopicGraph( - this IDataReader reader, + /*============================================================================================================================ + | METHOD: LOAD TOPIC GRAPH + \---------------------------------------------------------------------------------------------------------------------------*/ + internal static async Task LoadTopicGraphAsync( + this DbDataReader reader, int seedTopicId = -1, Topic? referenceTopic = null, bool? markDirty = null, - bool includeExternalReferences = true + bool includeExternalReferences = true, + CancellationToken cancellationToken = default ) { /*-------------------------------------------------------------------------------------------------------------------------- | Establish topic index \-------------------------------------------------------------------------------------------------------------------------*/ - var sqlDataReader = reader as SqlDataReader; var topics = referenceTopic is not null? referenceTopic.GetRootTopic().GetTopicIndex() : new(); var rootTopic = (Topic?)null; var preExistingIds = new HashSet(topics.Keys); @@ -78,7 +81,7 @@ internal static class SqlDataReaderExtensions { | Populate topics \-------------------------------------------------------------------------------------------------------------------------*/ Debug.WriteLine("SqlTopicRepository.Load(): AddTopic() [" + DateTime.Now + "]"); - while (reader.Read()) { + while (await reader.ReadAsync(cancellationToken).ConfigureAwait(false)) { // Add the topic to the topic graph var addedTopic = reader.AddTopic(topics, markDirty); @@ -133,9 +136,9 @@ internal static class SqlDataReaderExtensions { Debug.WriteLine("SqlTopicRepository.Load(): SetIndexedAttributes() [" + DateTime.Now + "]"); // Move to TopicAttributes dataset - reader.NextResult(); + await reader.NextResultAsync(cancellationToken).ConfigureAwait(false); - while (reader.Read()) { + while (await reader.ReadAsync(cancellationToken).ConfigureAwait(false)) { reader.SetIndexedAttributes(topics, markDirty); } @@ -145,11 +148,11 @@ internal static class SqlDataReaderExtensions { Debug.WriteLine("SqlTopicRepository.Load(): SetExtendedAttributes() [" + DateTime.Now + "]"); // Move to extended attributes dataset - reader.NextResult(); + await reader.NextResultAsync(cancellationToken).ConfigureAwait(false); // Loop through each extended attribute record associated with a specific topic - while (reader.Read()) { - sqlDataReader?.SetExtendedAttributes(topics, markDirty); + while (await reader.ReadAsync(cancellationToken).ConfigureAwait(false)) { + (reader as SqlDataReader)?.SetExtendedAttributes(topics, markDirty); } /*-------------------------------------------------------------------------------------------------------------------------- @@ -158,11 +161,11 @@ internal static class SqlDataReaderExtensions { Debug.WriteLine("SqlTopicRepository.Load(): SetRelationships() [" + DateTime.Now + "]"); // Move to the relationships dataset - reader.NextResult(); + await reader.NextResultAsync(cancellationToken).ConfigureAwait(false); // Loop through each relationship; multiple records may exist per topic if (includeExternalReferences) { - while (reader.Read()) { + while (await reader.ReadAsync(cancellationToken).ConfigureAwait(false)) { reader.SetRelationships(topics, markDirty); } } @@ -173,10 +176,10 @@ internal static class SqlDataReaderExtensions { Debug.WriteLine("SqlTopicRepository.Load(): SetReferences() [" + DateTime.Now + "]"); // Move to the version history dataset - reader.NextResult(); + await reader.NextResultAsync(cancellationToken).ConfigureAwait(false); // Loop through each version; multiple records may exist per topic - while (reader.Read()) { + while (await reader.ReadAsync(cancellationToken).ConfigureAwait(false)) { reader.SetReferences(topics, markDirty); } @@ -186,10 +189,10 @@ internal static class SqlDataReaderExtensions { Debug.WriteLine("SqlTopicRepository.Load(): SetVersionHistory() [" + DateTime.Now + "]"); // Move to the version history dataset - reader.NextResult(); + await reader.NextResultAsync(cancellationToken).ConfigureAwait(false); // Loop through each version; multiple records may exist per topic - while (reader.Read()) { + while (await reader.ReadAsync(cancellationToken).ConfigureAwait(false)) { reader.SetVersionHistory(topics); } @@ -289,7 +292,7 @@ internal static void FillChildren(this IDataReader reader, Topic parent, TopicIn /// internal static async Task FillChildrenAsync( - this SqlDataReader reader, + this DbDataReader reader, Topic parent, TopicIndex topics, CancellationToken cancellationToken diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index d591b0f3..5a504e53 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -55,7 +55,7 @@ public SqlTopicRepository(string connectionString) : base() { | METHOD: LOAD \---------------------------------------------------------------------------------------------------------------------------*/ /// - public override Topic Load( + public override async Task Load( string uniqueKey, Topic? referenceTopic = null, bool isRecursive = true, @@ -89,8 +89,8 @@ public override Topic Load( \-------------------------------------------------------------------------------------------------------------------------*/ try { - connection.Open(); - command.ExecuteNonQuery(); + await connection.OpenAsync().ConfigureAwait(false); + await command.ExecuteNonQueryAsync().ConfigureAwait(false); topicId = command.GetReturnCode(); @@ -113,12 +113,12 @@ public override Topic Load( /*-------------------------------------------------------------------------------------------------------------------------- | Return topic \-------------------------------------------------------------------------------------------------------------------------*/ - return Load(topicId, referenceTopic, isRecursive, payload); + return await Load(topicId, referenceTopic, isRecursive, payload).ConfigureAwait(false); } /// - public override Topic Load( + public override async Task Load( int topicId, Topic? referenceTopic = null, bool isRecursive = true, @@ -150,9 +150,9 @@ public override Topic Load( | Process database query \-------------------------------------------------------------------------------------------------------------------------*/ try { - connection.Open(); - using var reader = command.ExecuteReader(); - topic = reader.LoadTopicGraph(topicId, referenceTopic, false); + await connection.OpenAsync().ConfigureAwait(false); + using var reader = (SqlDataReader)await command.ExecuteReaderAsync().ConfigureAwait(false); + topic = await reader.LoadTopicGraphAsync(topicId, referenceTopic, false).ConfigureAwait(false); } /*-------------------------------------------------------------------------------------------------------------------------- @@ -202,7 +202,7 @@ public override Topic Load( } /// - public override Topic Load(int topicId, DateTime version, Topic? referenceTopic = null) { + public override async Task Load(int topicId, DateTime version, Topic? referenceTopic = null) { /*-------------------------------------------------------------------------------------------------------------------------- | Normalize parameters @@ -255,8 +255,8 @@ public override Topic Load(int topicId, DateTime version, Topic? referenceTopic | Process database query \-------------------------------------------------------------------------------------------------------------------------*/ try { - connection.Open(); - using var reader = command.ExecuteReader(); + await connection.OpenAsync().ConfigureAwait(false); + using var reader = (SqlDataReader)await command.ExecuteReaderAsync().ConfigureAwait(false); // Clear existing associations before repopulating from the historical version if (topic is not null) { @@ -270,11 +270,11 @@ public override Topic Load(int topicId, DateTime version, Topic? referenceTopic } // Load the historical version into the current topic graph - topic = reader.LoadTopicGraph( + topic = await reader.LoadTopicGraphAsync( topicId, referenceTopic, includeExternalReferences: referenceTopic is not null - ); + ).ConfigureAwait(false); } @@ -366,7 +366,7 @@ public override void Refresh(Topic referenceTopic, DateTime since) { try { connection.Open(); using var reader = command.ExecuteReader(); - reader.LoadTopicGraph(-1, referenceTopic.GetRootTopic(), false); + reader.LoadTopicGraphAsync(-1, referenceTopic.GetRootTopic(), false).GetAwaiter().GetResult(); } /*-------------------------------------------------------------------------------------------------------------------------- @@ -383,119 +383,7 @@ public override void Refresh(Topic referenceTopic, DateTime since) { \---------------------------------------------------------------------------------------------------------------------------*/ /// - public virtual void EnsureLoaded(Topic topic, TopicPayload payload) { - - /*-------------------------------------------------------------------------------------------------------------------------- - | Validate parameters - \-------------------------------------------------------------------------------------------------------------------------*/ - Contract.Requires(topic); - - /*-------------------------------------------------------------------------------------------------------------------------- - | Skip for new topics, as there's no persistent data to fetch - \-------------------------------------------------------------------------------------------------------------------------*/ - if (topic.IsNew) { - return; - } - - /*-------------------------------------------------------------------------------------------------------------------------- - | Filter to pending (not yet Loaded) payload - \-------------------------------------------------------------------------------------------------------------------------*/ - payload = topic.FilterPayload(payload); - - if (payload is TopicPayload.None) { - return; - } - - // Relationships and References themselves not by SqlTopicRepository; exit early if that's all that's pending so we don't - // open a database connection unnecessarily - if (!payload.HasFlag(TopicPayload.Children) && !payload.HasFlag(TopicPayload.ExtendedAttributes)) { - return; - } - - /*-------------------------------------------------------------------------------------------------------------------------- - | Establish database connection - \-------------------------------------------------------------------------------------------------------------------------*/ - using var connection = new SqlConnection(_connectionString); - using var command = new SqlCommand("GetTopics", connection) { - CommandType = CommandType.StoredProcedure - }; - - // Set the stored procedure parameters based on the TopicPayload enum values - AddEnsureLoadedParameters(command, topic.Id, payload); - - /*-------------------------------------------------------------------------------------------------------------------------- - | Process database query - >--------------------------------------------------------------------------------------------------------------------------- - | Use the full live graph as the topic index so already-resident relationship targets are found without extra round-trips. - | When filling Children, associations for the parent/seed topic are re-fetched alongside the children's; stale deferred - | entries are cleared before processing to prevent duplicates from accumulating in the Deferred collection. - \-------------------------------------------------------------------------------------------------------------------------*/ - var topics = topic.GetRootTopic().GetTopicIndex(); - var rawTopic = (ITopicBackingAccessor)topic; - - try { - - // Setup - connection.Open(); - using var reader = command.ExecuteReader(); - - // Children: Fill first result set; FillChildren() sets each child's Children.LoadState and marks the parent as Loaded - if (payload.HasFlag(TopicPayload.Children)) { - reader.FillChildren(topic, topics); - } - - // Otherwise, skip the first result set since the topic is already resident - else { - reader.NextResult(); - } - - // Indexed attributes - reader.NextResult(); - while (reader.Read()) { - reader.SetIndexedAttributes(topics, markDirty: false); - } - - // Extended attributes - reader.NextResult(); - while (reader.Read()) { - reader.SetExtendedAttributes(topics, markDirty: false, preserveDirty: true); - } - - // Clear stale deferred entries on the parent/seed topic before its associations are re-processed alongside children - if (payload.HasFlag(TopicPayload.Children)) { - rawTopic.Relationships.Deferred.Clear(); - rawTopic.References.Deferred.Clear(); - } - - // Relationships - reader.NextResult(); - while (reader.Read()) { - reader.SetRelationships(topics, markDirty: false); - } - - // References - reader.NextResult(); - while (reader.Read()) { - reader.SetReferences(topics, markDirty: false); - } - - } - catch (SqlException exception) { - throw new TopicRepositoryException($"Topic payload failed to load: '{exception.Message}'", exception); - } - - /*-------------------------------------------------------------------------------------------------------------------------- - | Mark confirmed payload as Loaded - >--------------------------------------------------------------------------------------------------------------------------- - | Children is excluded: Its LoadState is set inside FillChildren() after a successful fill. Relationships and References - | are computed from Deferred.Count and require no explicit assignment here. Only Extended Attributes needs to be set. - \-------------------------------------------------------------------------------------------------------------------------*/ - topic.SetLoadState(payload & TopicPayload.ExtendedAttributes, LoadState.Loaded); - - } - - /// - public virtual async Task EnsureLoadedAsync(Topic topic, TopicPayload payload, CancellationToken cancellationToken) { + public virtual async Task EnsureLoaded(Topic topic, TopicPayload payload, CancellationToken cancellationToken = default) { /*-------------------------------------------------------------------------------------------------------------------------- | Validate parameters @@ -642,7 +530,7 @@ bool persistRelationships \-------------------------------------------------------------------------------------------------------------------------*/ if (!extendedBoundaryLoaded) { if (extendedAttributeList.Any(a => a.IsDirty)) { - EnsureLoaded(topic, TopicPayload.ExtendedAttributes); + EnsureLoaded(topic, TopicPayload.ExtendedAttributes).GetAwaiter().GetResult(); extendedBoundaryLoaded = true; extendedAttributeList = GetAttributes(topic, isExtendedAttribute: true).ToList(); } diff --git a/OnTopic.TestDoubles/DummyTopicRepository.cs b/OnTopic.TestDoubles/DummyTopicRepository.cs index 9fbdafa2..bda2d3fb 100644 --- a/OnTopic.TestDoubles/DummyTopicRepository.cs +++ b/OnTopic.TestDoubles/DummyTopicRepository.cs @@ -36,26 +36,26 @@ public DummyTopicRepository() : base() { } | METHOD: LOAD \---------------------------------------------------------------------------------------------------------------------------*/ /// - public override Topic? Load( + public override Task Load( int topicId, Topic? referenceTopic = null, bool isRecursive = true, TopicPayload payload = TopicPayload.All - ) => null; + ) => Task.FromResult(null); /// - public override Topic? Load( + public override Task Load( string uniqueKey, Topic? referenceTopic = null, bool isRecursive = true, TopicPayload payload = TopicPayload.All - ) => null; + ) => Task.FromResult(null); /// - public override Topic? Load(Topic? topic, DateTime version) => throw new NotImplementedException(); + public override Task Load(Topic? topic, DateTime version) => throw new NotImplementedException(); /// - public override Topic? Load(int topicId, DateTime version, Topic? referenceTopic = null) => throw new NotImplementedException(); + public override Task Load(int topicId, DateTime version, Topic? referenceTopic = null) => throw new NotImplementedException(); /*============================================================================================================================ | METHOD: ROLLBACK diff --git a/OnTopic.TestDoubles/StubTopicRepository.cs b/OnTopic.TestDoubles/StubTopicRepository.cs index e9b4af18..74013a87 100644 --- a/OnTopic.TestDoubles/StubTopicRepository.cs +++ b/OnTopic.TestDoubles/StubTopicRepository.cs @@ -47,7 +47,7 @@ public StubTopicRepository() : base() { | METHOD: LOAD \---------------------------------------------------------------------------------------------------------------------------*/ /// - public override Topic? Load( + public override Task Load( int topicId, Topic? referenceTopic = null, bool isRecursive = true, @@ -80,12 +80,12 @@ public StubTopicRepository() : base() { /*-------------------------------------------------------------------------------------------------------------------------- | Return value \-------------------------------------------------------------------------------------------------------------------------*/ - return topic; + return Task.FromResult(topic); } /// - public override Topic? Load( + public override Task Load( string uniqueKey, Topic? referenceTopic = null, bool isRecursive = true, @@ -96,7 +96,7 @@ public StubTopicRepository() : base() { | Validate parameters \-------------------------------------------------------------------------------------------------------------------------*/ if (String.IsNullOrEmpty(uniqueKey)) { - return null; + return Task.FromResult(null); } /*-------------------------------------------------------------------------------------------------------------------------- @@ -121,12 +121,12 @@ public StubTopicRepository() : base() { /*-------------------------------------------------------------------------------------------------------------------------- | Return topic \-------------------------------------------------------------------------------------------------------------------------*/ - return topic; + return Task.FromResult(topic); } /// - public override Topic? Load(int topicId, DateTime version, Topic? referenceTopic = null) { + public override Task Load(int topicId, DateTime version, Topic? referenceTopic = null) { /*-------------------------------------------------------------------------------------------------------------------------- | Validate parameters @@ -173,7 +173,7 @@ public StubTopicRepository() : base() { /*-------------------------------------------------------------------------------------------------------------------------- | Return objects \-------------------------------------------------------------------------------------------------------------------------*/ - return topic?? throw new TopicNotFoundException(topicId); + return Task.FromResult(topic ?? throw new TopicNotFoundException(topicId)); } @@ -207,7 +207,7 @@ protected override void SaveTopic([NotNull]Topic topic, DateTime version, bool p /// without merging real blob data, allowing tests to exercise the fill path without a live /// database. /// - public virtual void EnsureLoaded(Topic topic, TopicPayload payload) { + public virtual Task EnsureLoaded(Topic topic, TopicPayload payload, CancellationToken cancellationToken = default) { /*-------------------------------------------------------------------------------------------------------------------------- | Validate parameters @@ -229,12 +229,8 @@ public virtual void EnsureLoaded(Topic topic, TopicPayload payload) { rawTopic.References.Deferred.Clear(); } - } - - /// - public virtual Task EnsureLoadedAsync(Topic topic, TopicPayload payload, CancellationToken cancellationToken) { - EnsureLoaded(topic, payload); return Task.CompletedTask; + } /*============================================================================================================================ diff --git a/OnTopic.Tests/HierarchicalTopicMappingServiceTest.cs b/OnTopic.Tests/HierarchicalTopicMappingServiceTest.cs index 129fd6ee..07f2a28d 100644 --- a/OnTopic.Tests/HierarchicalTopicMappingServiceTest.cs +++ b/OnTopic.Tests/HierarchicalTopicMappingServiceTest.cs @@ -57,7 +57,7 @@ public HierarchicalTopicMappingServiceTest(TopicInfrastructureFixture t.Key.EndsWith('1')); @@ -180,8 +180,8 @@ public async Task GetViewModel_WithValidationDelegate_ExcludesTopics() { [Fact] public async Task GetViewModel_WithDisabled_ExcludesDisabled() { - var rootTopic = _topicRepository.Load("Root:Web:Web_3")!; - var disabledTopic = _topicRepository.Load("Root:Web:Web_3:Web_3_0"); + var rootTopic = _topicRepository.Load("Root:Web:Web_3").GetAwaiter().GetResult()!; + var disabledTopic = _topicRepository.Load("Root:Web:Web_3:Web_3_0").GetAwaiter().GetResult(); Contract.Assume(disabledTopic); diff --git a/OnTopic.Tests/ITopicRepositoryTest.cs b/OnTopic.Tests/ITopicRepositoryTest.cs index 680bc0c2..6bd0fa46 100644 --- a/OnTopic.Tests/ITopicRepositoryTest.cs +++ b/OnTopic.Tests/ITopicRepositoryTest.cs @@ -65,7 +65,7 @@ public ITopicRepositoryTest(TopicInfrastructureFixture fixt [Fact] public void Load_Default_ReturnsTopicTopic() { - var rootTopic = _topicRepository.Load(); + var rootTopic = _topicRepository.Load().GetAwaiter().GetResult(); Assert.Equal(2, rootTopic?.Children.Count); Assert.Equal("Configuration", rootTopic?.Children.First().Key); @@ -81,7 +81,7 @@ public void Load_Default_ReturnsTopicTopic() { /// [Fact] public void Load_ValidUniqueKey_ReturnsCorrectTopic() => - Assert.Equal("Page", _topicRepository.Load("Root:Configuration:ContentTypes:Page")?.Key); + Assert.Equal("Page", _topicRepository.Load("Root:Configuration:ContentTypes:Page").GetAwaiter().GetResult()?.Key); /*============================================================================================================================ | TEST: LOAD: INVALID UNIQUE KEY: RETURNS NULL @@ -91,7 +91,7 @@ public void Load_ValidUniqueKey_ReturnsCorrectTopic() => /// [Fact] public void Load_InvalidUniqueKey_ReturnsTopic() => - Assert.Null(_topicRepository.Load("Root:Configuration:ContentTypes:InvalidContentType")); + Assert.Null(_topicRepository.Load("Root:Configuration:ContentTypes:InvalidContentType").GetAwaiter().GetResult()); /*============================================================================================================================ | TEST: LOAD: VALID TOPIC ID: RETURNS CORRECT TOPIC @@ -102,7 +102,7 @@ public void Load_InvalidUniqueKey_ReturnsTopic() => [Fact] public void Load_ValidTopicId_ReturnsCorrectTopic() { - var topic = _topicRepository.Load(11111); + var topic = _topicRepository.Load(11111).GetAwaiter().GetResult(); Assert.NotNull(topic); Assert.Equal("Web_1_1_1_1", topic?.Key); @@ -117,7 +117,7 @@ public void Load_ValidTopicId_ReturnsCorrectTopic() { /// [Fact] public void Load_InvalidTopicId_ReturnsNull() => - Assert.Null(_topicRepository.Load(9999999)); + Assert.Null(_topicRepository.Load(9999999).GetAwaiter().GetResult()); /*============================================================================================================================ | TEST: SAVE diff --git a/OnTopic.Tests/ReverseTopicMappingServiceTest.cs b/OnTopic.Tests/ReverseTopicMappingServiceTest.cs index 406b9804..42bbe014 100644 --- a/OnTopic.Tests/ReverseTopicMappingServiceTest.cs +++ b/OnTopic.Tests/ReverseTopicMappingServiceTest.cs @@ -334,7 +334,7 @@ public async Task Map_NestedTopics_ReturnsMappedTopic() { [Fact] public async Task Map_TopicReferences_ReturnsMappedTopic() { - var topic = _topicRepository.Load("Root:Configuration:ContentTypes:Attributes:Title"); + var topic = _topicRepository.Load("Root:Configuration:ContentTypes:Attributes:Title").GetAwaiter().GetResult(); Contract.Assume(topic); @@ -362,8 +362,8 @@ public async Task Map_TopicReferences_ReturnsMappedTopic() { [Fact] public async Task Map_NullTopicReference_Delete() { - var topic = _topicRepository.Load("Root:Configuration:ContentTypes:Attributes:Title"); - var baseTopic = _topicRepository.Load("Root:Configuration:ContentTypes:Attributes:Key"); + var topic = _topicRepository.Load("Root:Configuration:ContentTypes:Attributes:Title").GetAwaiter().GetResult(); + var baseTopic = _topicRepository.Load("Root:Configuration:ContentTypes:Attributes:Key").GetAwaiter().GetResult(); Contract.Assume(topic); diff --git a/OnTopic.Tests/SqlTopicRepositoryTest.cs b/OnTopic.Tests/SqlTopicRepositoryTest.cs index bd79da21..eeac8299 100644 --- a/OnTopic.Tests/SqlTopicRepositoryTest.cs +++ b/OnTopic.Tests/SqlTopicRepositoryTest.cs @@ -41,7 +41,7 @@ public void LoadTopicGraph_WithTopic_ReturnsTopic() { using var tableReader = new DataTableReader(topics); - var topic = tableReader.LoadTopicGraph(); + var topic = tableReader.LoadTopicGraphAsync().GetAwaiter().GetResult(); Assert.NotNull(topic); Assert.Equal(1, topic.Id); @@ -69,7 +69,7 @@ public void LoadTopicGraph_WithNewParent_UpdatesParent() { using var tableReader = new DataTableReader(topics); - tableReader.LoadTopicGraph(referenceTopic: topic); + tableReader.LoadTopicGraphAsync(referenceTopic: topic).GetAwaiter().GetResult(); Assert.Equal(parent2, child.Parent); @@ -93,7 +93,7 @@ public void LoadTopicGraph_WithAttributes_ReturnsAttributes() { using var tableReader = new DataTableReader([topics, attributes]); - var topic = tableReader.LoadTopicGraph(); + var topic = tableReader.LoadTopicGraphAsync().GetAwaiter().GetResult(); Assert.NotNull(topic); Assert.Equal(1, topic.Id); @@ -123,7 +123,7 @@ public void LoadTopicGraph_WithNullAttributes_RemovesAttribute() { using var tableReader = new DataTableReader([topics, attributes]); - tableReader.LoadTopicGraph(referenceTopic: topic); + tableReader.LoadTopicGraphAsync(referenceTopic: topic).GetAwaiter().GetResult(); Assert.Null(topic.Attributes.GetValue("Test")); @@ -149,7 +149,7 @@ public void LoadTopicGraph_WithRelationship_ReturnsRelationship() { using var tableReader = new DataTableReader([topics, empty, empty, relationships]); - var topic = tableReader.LoadTopicGraph(); + var topic = tableReader.LoadTopicGraphAsync().GetAwaiter().GetResult(); Assert.NotNull(topic); Assert.Equal(1, topic.Id); @@ -177,7 +177,7 @@ public void LoadTopicGraph_WithMissingRelationship_NotFullyLoaded() { using var tableReader = new DataTableReader([topics, empty, empty, relationships]); - var topic = tableReader.LoadTopicGraph(); + var topic = tableReader.LoadTopicGraphAsync().GetAwaiter().GetResult(); Assert.NotNull(topic); Assert.Equal(1, topic.Id); @@ -206,7 +206,7 @@ public void LoadTopicGraph_WithReference_ReturnsReference() { using var tableReader = new DataTableReader([topics, empty, empty, empty, references]); - var topic = tableReader.LoadTopicGraph(); + var topic = tableReader.LoadTopicGraphAsync().GetAwaiter().GetResult(); Assert.NotNull(topic); Assert.Equal(1, topic.Id); @@ -236,7 +236,7 @@ public void LoadTopicGraph_WithExternalReference_ReturnsReference() { using var tableReader = new DataTableReader([topics, empty, empty, empty, references]); - var topic = tableReader.LoadTopicGraph(1, referenceTopic, false); + var topic = tableReader.LoadTopicGraphAsync(1, referenceTopic, false).GetAwaiter().GetResult(); Assert.NotNull(topic); Assert.Equal(1, topic.Id); @@ -270,7 +270,7 @@ public void LoadTopicGraph_WithDeletedReference_RemovesExistingReference() { using var tableReader = new DataTableReader([topics, empty, empty, empty, references]); - tableReader.LoadTopicGraph(1, referenceTopic, false); + tableReader.LoadTopicGraphAsync(1, referenceTopic, false).GetAwaiter().GetResult(); Assert.Null(referenceTopic.References.GetValue("Reference")); Assert.Equal(LoadState.Loaded, referenceTopic.References.LoadState); @@ -296,7 +296,7 @@ public void LoadTopicGraph_WithMissingReference_NotFullyLoaded() { using var tableReader = new DataTableReader([topics, empty, empty, empty, references]); - var topic = tableReader.LoadTopicGraph(); + var topic = tableReader.LoadTopicGraphAsync().GetAwaiter().GetResult(); Assert.NotNull(topic); Assert.Equal(1, topic.Id); @@ -328,7 +328,7 @@ public void LoadTopicGraph_WithDeletedRelationship_RemovesRelationship() { using var tableReader = new DataTableReader([empty, empty, empty, relationships]); - tableReader.LoadTopicGraph(referenceTopic: related); + tableReader.LoadTopicGraphAsync(referenceTopic: related).GetAwaiter().GetResult(); Assert.Empty(topic.Relationships.GetValues("Test")); @@ -359,7 +359,7 @@ public void LoadTopicGraph_IndexedOnlyWithRelationship_ReturnsLoaded() { using var tableReader = new DataTableReader([topics, empty, empty, relationships]); - var topic = tableReader.LoadTopicGraph(); + var topic = tableReader.LoadTopicGraphAsync().GetAwaiter().GetResult(); Assert.NotNull(topic); Assert.True(topic.IsLoaded(TopicPayload.Relationships)); @@ -390,7 +390,7 @@ public void LoadTopicGraph_IndexedOnlyWithMissingRelationship_ReturnsNotLoaded() using var tableReader = new DataTableReader([topics, empty, empty, relationships]); - var topic = tableReader.LoadTopicGraph(); + var topic = tableReader.LoadTopicGraphAsync().GetAwaiter().GetResult(); Assert.NotNull(topic); Assert.False(topic.IsLoaded(TopicPayload.Relationships)); @@ -417,7 +417,7 @@ public void LoadTopicGraph_IndexedOnlyWithReference_ReturnsLoaded() { using var tableReader = new DataTableReader([topics, empty, empty, empty, references]); - var topic = tableReader.LoadTopicGraph(); + var topic = tableReader.LoadTopicGraphAsync().GetAwaiter().GetResult(); Assert.NotNull(topic); Assert.True(topic.IsLoaded(TopicPayload.References)); @@ -444,7 +444,7 @@ public void LoadTopicGraph_IndexedOnlyWithMissingReference_ReturnsNotLoaded() { using var tableReader = new DataTableReader([topics, empty, empty, empty, references]); - var topic = tableReader.LoadTopicGraph(); + var topic = tableReader.LoadTopicGraphAsync().GetAwaiter().GetResult(); Assert.NotNull(topic); Assert.False(topic.IsLoaded(TopicPayload.References)); @@ -471,7 +471,7 @@ public void LoadTopicGraph_WithMissingRelationship_SetsNotLoaded() { using var tableReader = new DataTableReader([topics, empty, empty, relationships]); - var topic = tableReader.LoadTopicGraph(); + var topic = tableReader.LoadTopicGraphAsync().GetAwaiter().GetResult(); Assert.NotNull(topic); Assert.False(topic.IsLoaded(TopicPayload.Relationships)); @@ -498,7 +498,7 @@ public void LoadTopicGraph_WithMissingReference_SetsNotLoaded() { using var tableReader = new DataTableReader([topics, empty, empty, empty, references]); - var topic = tableReader.LoadTopicGraph(); + var topic = tableReader.LoadTopicGraphAsync().GetAwaiter().GetResult(); Assert.NotNull(topic); Assert.False(topic.IsLoaded(TopicPayload.References)); @@ -524,7 +524,7 @@ public void LoadTopicGraph_WithVersionHistory_ReturnsVersions() { using var tableReader = new DataTableReader([topics, empty, empty, empty, empty, versions]); - var topic = tableReader.LoadTopicGraph(); + var topic = tableReader.LoadTopicGraphAsync().GetAwaiter().GetResult(); Assert.NotNull(topic); Assert.Equal(1, topic.Id); @@ -550,7 +550,7 @@ public void LoadTopicGraph_WithExtendedDeferredAndBlob_ReturnsNotLoaded() { using var tableReader = new DataTableReader(topics); - var topic = tableReader.LoadTopicGraph(); + var topic = tableReader.LoadTopicGraphAsync().GetAwaiter().GetResult(); Assert.NotNull(topic); Assert.False(topic.IsLoaded(TopicPayload.ExtendedAttributes)); @@ -574,7 +574,7 @@ public void LoadTopicGraph_WithExtendedDeferredAndNoBlob_ReturnsLoaded() { using var tableReader = new DataTableReader(topics); - var topic = tableReader.LoadTopicGraph(); + var topic = tableReader.LoadTopicGraphAsync().GetAwaiter().GetResult(); Assert.NotNull(topic); Assert.Equal(LoadState.Loaded, topic.Attributes.LoadState); @@ -598,7 +598,7 @@ public void LoadTopicGraph_WithExtendedIncludedAndBlob_ReturnsLoaded() { using var tableReader = new DataTableReader(topics); - var topic = tableReader.LoadTopicGraph(); + var topic = tableReader.LoadTopicGraphAsync().GetAwaiter().GetResult(); Assert.NotNull(topic); Assert.Equal(LoadState.Loaded, topic.Attributes.LoadState); @@ -622,7 +622,7 @@ public void LoadTopicGraph_WithHasChildrenFalse_ReturnsChildrenLoaded() { using var tableReader = new DataTableReader(topics); - var topic = tableReader.LoadTopicGraph(1); + var topic = tableReader.LoadTopicGraphAsync(1).GetAwaiter().GetResult(); Assert.True(topic?.IsLoaded(TopicPayload.Children)); @@ -646,7 +646,7 @@ public void LoadTopicGraph_WithHasChildrenAndLoadedChildren_ReturnsChildrenLoade using var tableReader = new DataTableReader(topics); - var topic = tableReader.LoadTopicGraph(1); + var topic = tableReader.LoadTopicGraphAsync(1).GetAwaiter().GetResult(); Assert.True(topic?.IsLoaded(TopicPayload.Children)); @@ -674,7 +674,7 @@ public void LoadTopicGraph_WithHasChildrenOnAncestorAndLoadedSubtree_SetsLoadSta // The seed topic is Child (2); Root (1) is on the ancestor chain and is NotLoaded. // The Child (seed) and Grandchild are in the fully loaded subtree and are Loaded. - var seedTopic = tableReader.LoadTopicGraph(2); + var seedTopic = tableReader.LoadTopicGraphAsync(2).GetAwaiter().GetResult(); var rootTopic = seedTopic?.Parent; Assert.Equal(LoadState.NotLoaded, rootTopic?.Children.LoadState); diff --git a/OnTopic.Tests/TestDoubles/TrackingTopicLoadResolver.cs b/OnTopic.Tests/TestDoubles/TrackingTopicLoadResolver.cs index 4ebb07ff..7fdfdfee 100644 --- a/OnTopic.Tests/TestDoubles/TrackingTopicLoadResolver.cs +++ b/OnTopic.Tests/TestDoubles/TrackingTopicLoadResolver.cs @@ -20,8 +20,7 @@ internal sealed class TrackingTopicLoadResolver : ITopicLoadResolver { | PROPERTY: WAS CALLED \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Returns if either or was invoked. + /// Returns if was invoked. /// public bool WasCalled { get; private set; } @@ -29,17 +28,7 @@ internal sealed class TrackingTopicLoadResolver : ITopicLoadResolver { | METHOD: ENSURE LOADED \---------------------------------------------------------------------------------------------------------------------------*/ /// - void ITopicLoadResolver.EnsureLoaded(Topic topic, TopicPayload payload) => WasCalled = true; - - /*============================================================================================================================ - | METHOD: ENSURE LOADED (ASYNC) - \---------------------------------------------------------------------------------------------------------------------------*/ - /// - Task ITopicLoadResolver.EnsureLoadedAsync( - Topic topic, - TopicPayload payload, - CancellationToken cancellationToken - ) { + Task ITopicLoadResolver.EnsureLoaded(Topic topic, TopicPayload payload, CancellationToken cancellationToken) { WasCalled = true; return Task.CompletedTask; } diff --git a/OnTopic.Tests/TopicMappingServiceTest.cs b/OnTopic.Tests/TopicMappingServiceTest.cs index 56f154ab..1642564b 100644 --- a/OnTopic.Tests/TopicMappingServiceTest.cs +++ b/OnTopic.Tests/TopicMappingServiceTest.cs @@ -849,7 +849,7 @@ public async Task Map_AlternateRelationship_ReturnsCorrectRelationship() { [Fact] public async Task Map_CustomCollection_ReturnsCollection() { - var topic = (ContentTypeDescriptor?)_topicRepository.Load("Root:Configuration:ContentTypes:Page"); + var topic = (ContentTypeDescriptor?)_topicRepository.Load("Root:Configuration:ContentTypes:Page").GetAwaiter().GetResult(); var target = await _mappingService.MapAsync(topic); Assert.NotNull(topic); @@ -995,7 +995,7 @@ public async Task Map_MapToParent_ReturnsMappedModel() { [Fact] public async Task Map_MapAs_ReturnsTopicReference() { - var topicReference = _topicRepository.Load(11111); + var topicReference = _topicRepository.Load(11111).GetAwaiter().GetResult(); Contract.Assume(topicReference); @@ -1020,7 +1020,7 @@ public async Task Map_MapAs_ReturnsTopicReference() { [Fact] public async Task Map_MapAs_ReturnsRelationships() { - var relatedTopic = _topicRepository.Load(11111); + var relatedTopic = _topicRepository.Load(11111).GetAwaiter().GetResult(); Contract.Assume(relatedTopic); @@ -1046,7 +1046,7 @@ public async Task Map_MapAs_ReturnsRelationships() { [Fact] public async Task Map_TopicReferencesAsAttribute_ReturnsMappedModel() { - var topicReference = _topicRepository.Load(11111); + var topicReference = _topicRepository.Load(11111).GetAwaiter().GetResult(); Contract.Assume(topicReference); @@ -1070,7 +1070,7 @@ public async Task Map_TopicReferencesAsAttribute_ReturnsMappedModel() { [Fact] public async Task Map_TopicReferences_ReturnsMappedModel() { - var topicReference = _topicRepository.Load(11111); + var topicReference = _topicRepository.Load(11111).GetAwaiter().GetResult(); var topic = new Topic("Test", "TopicReference"); diff --git a/OnTopic.Tests/TopicQueryingTest.cs b/OnTopic.Tests/TopicQueryingTest.cs index 145acead..23cabb8c 100644 --- a/OnTopic.Tests/TopicQueryingTest.cs +++ b/OnTopic.Tests/TopicQueryingTest.cs @@ -225,7 +225,7 @@ public void GetByUniqueKey_InvalidKey_ReturnsNull() { [Fact] public void GetContentType_ValidContentType_ReturnsContentType() { - var topic = _topicRepository.Load(11111); + var topic = _topicRepository.Load(11111).GetAwaiter().GetResult(); var contentTypeDescriptor = topic?.GetContentTypeDescriptor(); Assert.NotNull(contentTypeDescriptor); @@ -243,7 +243,7 @@ public void GetContentType_ValidContentType_ReturnsContentType() { [Fact] public void GetContentType_InvalidContentType_ReturnsNull() { - var parentTopic = _topicRepository.Load(11111); + var parentTopic = _topicRepository.Load(11111).GetAwaiter().GetResult(); var topic = new Topic("Test", "NonExistent", parentTopic); var contentTypeDescriptor = topic.GetContentTypeDescriptor(); @@ -268,7 +268,7 @@ public void GetContentType_InvalidContentType_ReturnsNull() { [Fact] public void GetContentType_InvalidType_ReturnsNull() { - var parentTopic = _topicRepository.Load(11111); + var parentTopic = _topicRepository.Load(11111).GetAwaiter().GetResult(); var topic = new Topic("Test", "Title", parentTopic); var contentTypeDescriptor = topic.GetContentTypeDescriptor(); diff --git a/OnTopic.Tests/TopicRepositoryBaseTest.cs b/OnTopic.Tests/TopicRepositoryBaseTest.cs index 3f3719ef..d6170ebe 100644 --- a/OnTopic.Tests/TopicRepositoryBaseTest.cs +++ b/OnTopic.Tests/TopicRepositoryBaseTest.cs @@ -58,7 +58,7 @@ public TopicRepositoryBaseTest() { [Fact] public void Load_ValidTopicId_ReturnsExpectedTopic() { - var topic = _topicRepository.Load(11111); + var topic = _topicRepository.Load(11111).GetAwaiter().GetResult(); Assert.Equal(11111, topic?.Id); @@ -73,7 +73,7 @@ public void Load_ValidTopicId_ReturnsExpectedTopic() { /// [Fact] public void Load_InvalidTopicId_ReturnsExpectedTopic() => - Assert.Null(_topicRepository.Load(11113)); + Assert.Null(_topicRepository.Load(11113).GetAwaiter().GetResult()); /*============================================================================================================================ | TEST: LOAD: NEGATIVE TOPIC ID: RETURNS ROOT TOPIC @@ -84,7 +84,7 @@ public void Load_InvalidTopicId_ReturnsExpectedTopic() => /// [Fact] public void Load_NegativeTopicId_ReturnsRootTopic() => - Assert.Equal("Root", _cachedTopicRepository.Load(-2)?.GetUniqueKey()); + Assert.Equal("Root", _cachedTopicRepository.Load(-2).GetAwaiter().GetResult()?.GetUniqueKey()); /*============================================================================================================================ | TEST: LOAD: NARROW PAYLOAD: RETURNS TOPIC @@ -97,7 +97,7 @@ public void Load_NegativeTopicId_ReturnsRootTopic() => [Fact] public void Load_WithNarrowPayload_ReturnsTopic() { - var topic = _topicRepository.Load(11111, payload: TopicPayload.None); + var topic = _topicRepository.Load(11111, payload: TopicPayload.None).GetAwaiter().GetResult(); Assert.NotNull(topic); @@ -114,7 +114,7 @@ public void Load_WithNarrowPayload_ReturnsTopic() { [Fact] public void Load_WithNarrowPayload_ExtendedAttributesLoaded() { - var topic = _topicRepository.Load(11111, payload: TopicPayload.None); + var topic = _topicRepository.Load(11111, payload: TopicPayload.None).GetAwaiter().GetResult(); Assert.NotNull(topic); Assert.Equal(LoadState.Loaded, topic.Attributes.LoadState); @@ -132,7 +132,7 @@ public void Load_WithNarrowPayload_ExtendedAttributesLoaded() { public void Load_ValidDate_ReturnsTopic() { var version = DateTime.UtcNow.AddDays(-1); - var topic = _cachedTopicRepository.Load(11111, version); + var topic = _cachedTopicRepository.Load(11111, version).GetAwaiter().GetResult(); Assert.True(topic?.VersionHistory.Contains(version)); Assert.Equal(version.AddTicks(-(version.Ticks % TimeSpan.TicksPerSecond)), topic?.LastModified); @@ -150,7 +150,7 @@ public void Load_ValidDate_ReturnsTopic() { public void Rollback_Topic_UpdatesLastModified() { var version = DateTime.UtcNow.AddDays(-1); - var topic = _topicRepository.Load(11111); + var topic = _topicRepository.Load(11111).GetAwaiter().GetResult(); if (topic is not null) { topic.VersionHistory.Add(version); @@ -170,8 +170,8 @@ public void Rollback_Topic_UpdatesLastModified() { /// confirms that an exception is thrown. /// [Fact] - public void Load_FutureDate_ThrowsException() => - Assert.Throws(() => + public async Task Load_FutureDate_ThrowsException() => + await Assert.ThrowsAsync(() => _cachedTopicRepository.Load(1111, DateTime.UtcNow.AddDays(1)) ); @@ -183,8 +183,8 @@ public void Load_FutureDate_ThrowsException() => /// introduced and ensures that an exception is thrown. /// [Fact] - public void Load_OldDate_ThrowsException() => - Assert.Throws(() => + public async Task Load_OldDate_ThrowsException() => + await Assert.ThrowsAsync(() => _cachedTopicRepository.Load(1111, new DateTime(2010, 10, 15)) ); @@ -660,7 +660,7 @@ public void GetContentTypeDescriptor_GetValidContentType_ReturnsContentType() { [Fact] public void GetContentTypeDescriptor_GetNewContentType_ReturnsFromTopicGraph() { - var rootTopic = _topicRepository.Load("Root"); + var rootTopic = _topicRepository.Load("Root").GetAwaiter().GetResult(); var contentTypes = _topicRepository.GetContentTypeDescriptors(); var rootContentType = contentTypes.GetValue("ContentTypes"); var newContentType = new ContentTypeDescriptor("NewContentType", "ContentTypeDescriptor", rootContentType); @@ -685,7 +685,7 @@ public void GetContentTypeDescriptor_GetNewContentType_ReturnsFromTopicGraph() { public void GetContentTypeDescriptor_MissingRootContentType_ReturnsNull() { var topicRepository = new StubTopicRepository(); - var configuration = topicRepository.Load("Root:Configuration"); + var configuration = topicRepository.Load("Root:Configuration").GetAwaiter().GetResult(); var topic = new Topic("Test", "Page"); topicRepository.Delete(configuration!, true); @@ -772,7 +772,7 @@ public void Save_ContentTypeDescriptor_UpdatesPermittedContentTypes() { [Fact] public void Save_NewTopic_UpdatesVersionHistory() { - var parent = _topicRepository.Load("Root:Web:Web_3:Web_3_0"); + var parent = _topicRepository.Load("Root:Web:Web_3:Web_3_0").GetAwaiter().GetResult(); var topic = new Topic("Test", "Page", parent); _topicRepository.Save(topic); @@ -791,7 +791,7 @@ public void Save_NewTopic_UpdatesVersionHistory() { [Fact] public void Save_IsRecursive_SavesChild() { - var parent = _topicRepository.Load("Root:Web:Web_3:Web_3_0"); + var parent = _topicRepository.Load("Root:Web:Web_3:Web_3_0").GetAwaiter().GetResult(); var topic = new Topic("Test", "Page", parent); var child = new Topic("Child", "Page", topic); @@ -812,7 +812,7 @@ public void Save_IsRecursive_SavesChild() { [Fact] public void Save_UnresolvedReference_Resolves() { - var parent = _topicRepository.Load("Root:Web:Web_3:Web_3_0"); + var parent = _topicRepository.Load("Root:Web:Web_3:Web_3_0").GetAwaiter().GetResult(); var topic = new Topic("Test", "Page", parent); var reference = new Topic("Reference", "Page", topic); @@ -832,7 +832,7 @@ public void Save_UnresolvedReference_Resolves() { [Fact] public void Save_UnresolvedReference_ThrowsException() { - var parent = _topicRepository.Load("Root:Web:Web_3:Web_3_0"); + var parent = _topicRepository.Load("Root:Web:Web_3:Web_3_0").GetAwaiter().GetResult(); var topic = new Topic("Test", "Page", parent); var reference = new Topic("Reference", "Page", parent); @@ -999,7 +999,7 @@ public void Load_TopicLoadedEvent_IsRaised() { _cachedTopicRepository.TopicLoaded += eventHandler; - var topic = _topicRepository.Load("Root:Web"); + var topic = _topicRepository.Load("Root:Web").GetAwaiter().GetResult(); _cachedTopicRepository.TopicLoaded -= eventHandler; @@ -1020,12 +1020,12 @@ public void Load_TopicLoadedEvent_IsRaised() { public void Load_TopicLoadedEvent_IsRaisedWithVersion() { var hasFired = false; - var topicId = _topicRepository.Load("Root:Web")?.Id; + var topicId = _topicRepository.Load("Root:Web").GetAwaiter().GetResult()?.Id; var version = DateTime.UtcNow; _cachedTopicRepository.TopicLoaded += eventHandler; - var topic = _topicRepository.Load(topicId?? -1, version); + var topic = _topicRepository.Load(topicId?? -1, version).GetAwaiter().GetResult(); _cachedTopicRepository.TopicLoaded -= eventHandler; @@ -1145,7 +1145,7 @@ public void Save_TopicMovedEvent_IsRaised() { [Fact] public void Save_NewTopic_StampsResolver() { - var parent = _topicRepository.Load("Root:Web:Web_3:Web_3_0"); + var parent = _topicRepository.Load("Root:Web:Web_3:Web_3_0").GetAwaiter().GetResult(); var topic = new Topic("Test", "Page", parent); _topicRepository.Save(topic); @@ -1187,7 +1187,7 @@ public void Save_NotLoadedChildren_SkipsRecursiveDescent() { [Fact] public void EnsureLoaded_ExtendedAttributesNotLoaded_MarksLoaded() { - var topic = _topicRepository.Load(11111); + var topic = _topicRepository.Load(11111).GetAwaiter().GetResult(); topic!.Attributes.LoadState = LoadState.NotLoaded; topic.EnsureLoaded(TopicPayload.ExtendedAttributes); @@ -1207,7 +1207,7 @@ public void EnsureLoaded_ExtendedAttributesNotLoaded_MarksLoaded() { [Fact] public void EnsureLoaded_MixedBoundaries_SkipsLoadedBoundaries() { - var topic = _topicRepository.Load(11111); + var topic = _topicRepository.Load(11111).GetAwaiter().GetResult(); topic!.Attributes.LoadState = LoadState.NotLoaded; Assert.True(topic.IsLoaded(TopicPayload.Children)); @@ -1234,7 +1234,7 @@ public void EnsureLoaded_MixedBoundaries_SkipsLoadedBoundaries() { [Fact] public void EnsureLoaded_RelationshipsNotLoaded_MarksLoaded() { - var topic = _topicRepository.Load(11111); + var topic = _topicRepository.Load(11111).GetAwaiter().GetResult(); topic!.Relationships.Deferred.Add(new("_stub", 11111)); topic.EnsureLoaded(TopicPayload.Relationships); @@ -1259,7 +1259,7 @@ public void EnsureLoaded_RelationshipsNotLoaded_MarksLoaded() { [Fact] public void EnsureLoaded_ReferencesNotLoaded_MarksLoaded() { - var topic = _topicRepository.Load(11111); + var topic = _topicRepository.Load(11111).GetAwaiter().GetResult(); topic!.References.Deferred.Add(new("_stub", 11111)); topic.EnsureLoaded(TopicPayload.References); @@ -1279,7 +1279,7 @@ public void EnsureLoaded_ReferencesNotLoaded_MarksLoaded() { [Fact] public void IsLoaded_ChildrenNotLoadedState_TriggersEnsureLoaded() { - var topic = _topicRepository.Load(11111); + var topic = _topicRepository.Load(11111).GetAwaiter().GetResult(); topic!.SetLoadState(TopicPayload.Children, LoadState.NotLoaded); _ = topic.Children; @@ -1299,7 +1299,7 @@ public void IsLoaded_ChildrenNotLoadedState_TriggersEnsureLoaded() { [Fact] public void IsLoaded_ChildrenLoadedState_DoesNotCallResolver() { - var topic = _topicRepository.Load(11111); + var topic = _topicRepository.Load(11111).GetAwaiter().GetResult(); Assert.True(topic!.IsLoaded(TopicPayload.Children)); _ = topic.Children; @@ -1319,7 +1319,7 @@ public void IsLoaded_ChildrenLoadedState_DoesNotCallResolver() { [Fact] public void IsLoaded_RelationshipsNotLoadedState_TriggersEnsureLoaded() { - var topic = _topicRepository.Load(11111); + var topic = _topicRepository.Load(11111).GetAwaiter().GetResult(); topic!.Relationships.Deferred.Add(new("_stub", 11111)); _ = topic.Relationships; @@ -1339,7 +1339,7 @@ public void IsLoaded_RelationshipsNotLoadedState_TriggersEnsureLoaded() { [Fact] public void IsLoaded_RelationshipsLoadedState_DoesNotCallResolver() { - var topic = _topicRepository.Load(11111); + var topic = _topicRepository.Load(11111).GetAwaiter().GetResult(); Assert.True(topic!.IsLoaded(TopicPayload.Relationships)); _ = topic.Relationships; @@ -1359,7 +1359,7 @@ public void IsLoaded_RelationshipsLoadedState_DoesNotCallResolver() { [Fact] public void IsLoaded_ReferencesNotLoadedState_TriggersEnsureLoaded() { - var topic = _topicRepository.Load(11111); + var topic = _topicRepository.Load(11111).GetAwaiter().GetResult(); topic!.References.Deferred.Add(new("_stub", 11111)); _ = topic.References; @@ -1379,7 +1379,7 @@ public void IsLoaded_ReferencesNotLoadedState_TriggersEnsureLoaded() { [Fact] public void IsLoaded_ReferencesLoadedState_DoesNotCallResolver() { - var topic = _topicRepository.Load(11111); + var topic = _topicRepository.Load(11111).GetAwaiter().GetResult(); Assert.True(topic!.IsLoaded(TopicPayload.References)); _ = topic.References; @@ -1399,7 +1399,7 @@ public void IsLoaded_ReferencesLoadedState_DoesNotCallResolver() { [Fact] public void EnsureLoaded_ChildrenNotLoaded_MarksLoaded() { - var topic = _topicRepository.Load(11111); + var topic = _topicRepository.Load(11111).GetAwaiter().GetResult(); topic!.SetLoadState(TopicPayload.Children, LoadState.NotLoaded); topic.EnsureLoaded(TopicPayload.Children); @@ -1449,7 +1449,7 @@ public void Move_TopicMovedEvent_IsRaised() { public void EnsureLoaded_WithMissingRelationshipTarget_ResolvesAndConnects() { // Get the root topic from cache; seed a deferred entry to simulate a pending relationship target - var source = _cachedTopicRepository.Load(-1)!; + var source = _cachedTopicRepository.Load(-1).GetAwaiter().GetResult()!; source.Relationships.Deferred.Add(new("_stub", 11111)); // Act: EnsureLoaded re-queries, finds the missing target, loads it, and connects the edge @@ -1471,7 +1471,7 @@ public void EnsureLoaded_WithMissingRelationshipTarget_ResolvesAndConnects() { public void EnsureLoaded_Relationships_AlreadyLoaded_SkipsFill() { // Get the root topic; relationships start as Loaded (Deferred is empty) after initialization - var source = _cachedTopicRepository.Load(-1)!; + var source = _cachedTopicRepository.Load(-1).GetAwaiter().GetResult()!; // Act _cachedTopicRepository.EnsureLoaded(source, TopicPayload.Relationships); diff --git a/OnTopic/Mapping/Hierarchical/HierarchicalTopicMappingService{T}.cs b/OnTopic/Mapping/Hierarchical/HierarchicalTopicMappingService{T}.cs index ed66124e..12646125 100644 --- a/OnTopic/Mapping/Hierarchical/HierarchicalTopicMappingService{T}.cs +++ b/OnTopic/Mapping/Hierarchical/HierarchicalTopicMappingService{T}.cs @@ -72,7 +72,7 @@ public class HierarchicalTopicMappingService(ITopicRepository topicRepository \-------------------------------------------------------------------------------------------------------------------------*/ if (navigationRootTopic is null) { Contract.Assume(!String.IsNullOrEmpty(defaultRoot), nameof(defaultRoot)); - navigationRootTopic = TopicRepository.Load(defaultRoot, currentTopic); + navigationRootTopic = TopicRepository.Load(defaultRoot, currentTopic).GetAwaiter().GetResult(); } /*-------------------------------------------------------------------------------------------------------------------------- diff --git a/OnTopic/Mapping/Reverse/ReverseTopicMappingService.cs b/OnTopic/Mapping/Reverse/ReverseTopicMappingService.cs index 723f686b..c48bddaa 100644 --- a/OnTopic/Mapping/Reverse/ReverseTopicMappingService.cs +++ b/OnTopic/Mapping/Reverse/ReverseTopicMappingService.cs @@ -294,13 +294,13 @@ await MapAsync( SetScalarValue(source, target, memberAccessor, attributePrefix); return; case ModelType.Relationship: - SetRelationships(source, target, memberAccessor, attributePrefix); + await SetRelationships(source, target, memberAccessor, attributePrefix).ConfigureAwait(false); return; case ModelType.NestedTopic: await SetNestedTopicsAsync(source, target, memberAccessor, attributePrefix).ConfigureAwait(false); return; case ModelType.Reference: - SetReference(source, target, memberAccessor, attributePrefix); + await SetReference(source, target, memberAccessor, attributePrefix).ConfigureAwait(false); return; } @@ -374,7 +374,7 @@ private static void SetScalarValue( /// The entity to map the data to. /// The with details about the property's attributes. /// The prefix to apply to the attributes. - private void SetRelationships( + private async Task SetRelationships( object source, Topic target, MemberAccessor memberAccessor, @@ -402,7 +402,7 @@ private void SetRelationships( | Set relationships for each \-------------------------------------------------------------------------------------------------------------------------*/ foreach (IAssociatedTopicBindingModel relationship in sourceList) { - var targetTopic = _topicRepository.Load(relationship.UniqueKey, target); + var targetTopic = await _topicRepository.Load(relationship.UniqueKey, target).ConfigureAwait(false); if (targetTopic is null) { throw new MappingModelValidationException( $"The relationship '{relationship.UniqueKey}' mapped in the '{memberAccessor.Name}' property could not be " + @@ -473,7 +473,7 @@ private async Task SetNestedTopicsAsync( /// The entity to map the data to. /// The with details about the property's attributes. /// The prefix to apply to the attributes. - private void SetReference( + private async Task SetReference( object source, Topic target, MemberAccessor memberAccessor, @@ -503,7 +503,7 @@ private void SetReference( /*-------------------------------------------------------------------------------------------------------------------------- | Identify target value \-------------------------------------------------------------------------------------------------------------------------*/ - var topicReference = _topicRepository.Load(modelReference.UniqueKey, target); + var topicReference = await _topicRepository.Load(modelReference.UniqueKey, target).ConfigureAwait(false); /*-------------------------------------------------------------------------------------------------------------------------- | Provide error handling diff --git a/OnTopic/Mapping/TopicMappingService.cs b/OnTopic/Mapping/TopicMappingService.cs index 2f56b62f..11165068 100644 --- a/OnTopic/Mapping/TopicMappingService.cs +++ b/OnTopic/Mapping/TopicMappingService.cs @@ -569,7 +569,7 @@ await MapAsync( return null; } else if (itemMetadata.Type.IsClass && associations.HasFlag(AssociationTypes.References)) { - var topicReference = getTopicReference(); + var topicReference = await getTopicReference().ConfigureAwait(false); if (topicReference is not null) { value = await GetTopicReferenceAsync(topicReference, targetType, itemMetadata, cache).ConfigureAwait(false); } @@ -583,7 +583,7 @@ await MapAsync( /*-------------------------------------------------------------------------------------------------------------------------- | Get Topic Reference \-------------------------------------------------------------------------------------------------------------------------*/ - Topic? getTopicReference() { + async Task getTopicReference() { // Check for standard topic reference var topicReference = source.References.GetValue(configuration.GetCompositeAttributeKey(attributePrefix)); @@ -599,7 +599,7 @@ await MapAsync( topicReferenceId = source.Attributes.GetInteger($"{configuration.GetCompositeAttributeKey(attributePrefix)}Id", 0); } if (topicReferenceId > 0) { - topicReference = _topicRepository.Load(topicReferenceId, source); + topicReference = await _topicRepository.Load(topicReferenceId, source).ConfigureAwait(false); } return topicReference; @@ -803,7 +803,7 @@ private async Task> GetSourceCollectionAsync( /*-------------------------------------------------------------------------------------------------------------------------- | Warm lazy-loaded payload before probing collections \-------------------------------------------------------------------------------------------------------------------------*/ - await source.EnsureLoadedAsync(AssociationMap.PayloadMappings[configuration.CollectionType]).ConfigureAwait(false); + await source.EnsureLoaded(AssociationMap.PayloadMappings[configuration.CollectionType]).ConfigureAwait(false); var listSource = (IList)[]; var collectionKey = configuration.CollectionKey; var collectionType = configuration.CollectionType; @@ -871,7 +871,7 @@ sourcePropertyValue[0] is Topic \-------------------------------------------------------------------------------------------------------------------------*/ if (listSource.Count == 0 && !String.IsNullOrWhiteSpace(configuration.MetadataKey)) { var metadataKey = $"Root:Configuration:Metadata:{configuration.MetadataKey}:LookupList"; - var metadataParent = _topicRepository.Load(metadataKey, source); + var metadataParent = await _topicRepository.Load(metadataKey, source).ConfigureAwait(false); if (metadataParent is not null) { listSource = [.. metadataParent.Children]; } diff --git a/OnTopic/Repositories/ITopicLoadResolver.cs b/OnTopic/Repositories/ITopicLoadResolver.cs index f212866b..6c4c489e 100644 --- a/OnTopic/Repositories/ITopicLoadResolver.cs +++ b/OnTopic/Repositories/ITopicLoadResolver.cs @@ -24,9 +24,6 @@ public interface ITopicLoadResolver { /// fetching and merging whichever of them are not yet and silently skipping those already /// loaded. Invoked by the autoloading property getters, each with its own flag. /// - void EnsureLoaded(Topic topic, TopicPayload payload); - - /// - Task EnsureLoadedAsync(Topic topic, TopicPayload payload, CancellationToken cancellationToken = default); + Task EnsureLoaded(Topic topic, TopicPayload payload, CancellationToken cancellationToken = default); } //Interface \ No newline at end of file diff --git a/OnTopic/Repositories/ITopicRepository.cs b/OnTopic/Repositories/ITopicRepository.cs index bc47c623..e5322144 100644 --- a/OnTopic/Repositories/ITopicRepository.cs +++ b/OnTopic/Repositories/ITopicRepository.cs @@ -86,7 +86,7 @@ public interface ITopicRepository { /// Loads the entire root topic graph, including all descendants. /// /// A topic object. - public Topic? Load() => Load(-1); + public Task Load() => Load(-1); /// /// Loads a (and, optionally, all of its descendants) based on the specified /// Specifies which data to include with each topic. /// A topic object. - Topic? Load( + Task Load( int topicId, Topic? referenceTopic = null, bool isRecursive = true, @@ -127,7 +127,7 @@ public interface ITopicRepository { /// for details. /// /// A topic object. - Topic? Load( + Task Load( string uniqueKey, Topic? referenceTopic = null, bool isRecursive = true, @@ -137,7 +137,7 @@ public interface ITopicRepository { /// [ExcludeFromCodeCoverage] [Obsolete("This overload has been removed in preference for Load(string, Topic, Boolean).")] - Topic? Load(string? uniqueKey, bool isRecursive); + Task Load(string? uniqueKey, bool isRecursive); /// /// Loads a specific version of a based on its and —are integrated with existing entities. /// /// A topic object. - Topic? Load(int topicId, DateTime version, Topic? referenceTopic = null); + Task Load(int topicId, DateTime version, Topic? referenceTopic = null); /// - Topic? Load(Topic topic, DateTime version); + Task Load(Topic topic, DateTime version); /*============================================================================================================================ | METHOD: ROLLBACK diff --git a/OnTopic/Repositories/ObservableTopicRepository.cs b/OnTopic/Repositories/ObservableTopicRepository.cs index a44125b7..81ee4f59 100644 --- a/OnTopic/Repositories/ObservableTopicRepository.cs +++ b/OnTopic/Repositories/ObservableTopicRepository.cs @@ -209,10 +209,10 @@ public event EventHandler? TopicRenamed { | METHOD: LOAD \---------------------------------------------------------------------------------------------------------------------------*/ /// - public virtual Topic? Load() => Load(-1); + public virtual Task Load() => Load(-1); /// - public abstract Topic? Load( + public abstract Task Load( int topicId, Topic? referenceTopic = null, bool isRecursive = true, @@ -220,7 +220,7 @@ public event EventHandler? TopicRenamed { ); /// - public abstract Topic? Load( + public abstract Task Load( string uniqueKey, Topic? referenceTopic = null, bool isRecursive = true, @@ -230,13 +230,13 @@ public event EventHandler? TopicRenamed { /// [ExcludeFromCodeCoverage] [Obsolete("This overload has been removed in preference for Load(string, Topic, Boolean).")] - public Topic? Load(string? uniqueKey, bool isRecursive) => throw new NotImplementedException(); + public Task Load(string? uniqueKey, bool isRecursive) => throw new NotImplementedException(); /// - public abstract Topic? Load(Topic topic, DateTime version); + public abstract Task Load(Topic topic, DateTime version); /// - public abstract Topic? Load(int topicId, DateTime version, Topic? referenceTopic = null); + public abstract Task Load(int topicId, DateTime version, Topic? referenceTopic = null); /*============================================================================================================================ | METHOD: REFRESH diff --git a/OnTopic/Repositories/TopicRepository.cs b/OnTopic/Repositories/TopicRepository.cs index 475217a6..1388421e 100644 --- a/OnTopic/Repositories/TopicRepository.cs +++ b/OnTopic/Repositories/TopicRepository.cs @@ -57,7 +57,7 @@ public override ContentTypeDescriptorCollection GetContentTypeDescriptors() { var configuration = (Topic?)null; try { - configuration = Load("Root:Configuration"); + configuration = Load("Root:Configuration").GetAwaiter().GetResult(); } catch (TopicNotFoundException) { //Swallow missing configuration, as this is an expected condition when working with a new database @@ -218,7 +218,7 @@ protected ContentTypeDescriptorCollection SetContentTypeDescriptors(ContentTypeD | METHOD: LOAD \---------------------------------------------------------------------------------------------------------------------------*/ /// - public override Topic? Load(Topic topic, DateTime version) { + public override Task Load(Topic topic, DateTime version) { Contract.Requires(topic, nameof(topic)); Contract.Requires( !topic.IsNew, diff --git a/OnTopic/Repositories/TopicRepositoryDecorator.cs b/OnTopic/Repositories/TopicRepositoryDecorator.cs index 126fd587..1363ca7c 100644 --- a/OnTopic/Repositories/TopicRepositoryDecorator.cs +++ b/OnTopic/Repositories/TopicRepositoryDecorator.cs @@ -77,10 +77,10 @@ protected TopicRepositoryDecorator(ITopicRepository topicRepository) : base() { | METHOD: LOAD \---------------------------------------------------------------------------------------------------------------------------*/ /// - public override Topic? Load() => Load(-1); + public override Task Load() => Load(-1); /// - public override Topic? Load( + public override Task Load( int topicId, Topic? referenceTopic = null, bool isRecursive = true, @@ -89,7 +89,7 @@ protected TopicRepositoryDecorator(ITopicRepository topicRepository) : base() { TopicRepository.Load(topicId, referenceTopic, isRecursive, payload); /// - public override Topic? Load( + public override Task Load( string uniqueKey, Topic? referenceTopic = null, bool isRecursive = true, @@ -98,11 +98,11 @@ protected TopicRepositoryDecorator(ITopicRepository topicRepository) : base() { TopicRepository.Load(uniqueKey, referenceTopic, isRecursive, payload); /// - public override Topic? Load(Topic topic, DateTime version) + public override Task Load(Topic topic, DateTime version) => TopicRepository.Load(topic, version); /// - public override Topic? Load(int topicId, DateTime version, Topic? referenceTopic = null) => + public override Task Load(int topicId, DateTime version, Topic? referenceTopic = null) => TopicRepository.Load(topicId, version, referenceTopic); /*============================================================================================================================ diff --git a/OnTopic/Topic.cs b/OnTopic/Topic.cs index 49f27e3e..48d6a857 100644 --- a/OnTopic/Topic.cs +++ b/OnTopic/Topic.cs @@ -165,7 +165,7 @@ public Topic? Parent { public KeyedTopicCollection Children { get { if (_children.LoadState is LoadState.NotLoaded) { - Resolver?.EnsureLoaded(this, TopicPayload.Children); + EnsureLoaded(TopicPayload.Children).GetAwaiter().GetResult(); } return _children; } @@ -269,47 +269,19 @@ public TopicPayload FilterPayload(TopicPayload payload) { \---------------------------------------------------------------------------------------------------------------------------*/ /// /// Ensures each requested flag has been retrieved, while fetching and merging whichever of - /// them are not yet , and silently skipping those already are. Returns immediately if the - /// resolver is absent or the topic is new. + /// them are not yet , and silently skipping those that already are. Returns immediately if + /// the resolver is absent or the topic is new. /// /// - /// The synchronous form backs the autoloading property getters (e.g., the getter); the asynchronous - /// form is for callers, such as a mapping or navigation service, that need to prepopulate one or more payload before - /// accessing them, thus avoiding a synchronous block on a "cold" node. A flag call lets those callers request everything a - /// node's mapping needs in a single round trip. + /// Callers such as a mapping or navigation service can await this to prepopulate one or more payloads before accessing + /// them, thus avoiding a synchronous block on a "cold" node. The autoloading property getters (e.g., ) + /// call this synchronously via GetAwaiter().GetResult() as an accepted sync-over-async boundary. /// /// /// One or more flags identifying the payload that should be ensured to be loaded. /// - public void EnsureLoaded(TopicPayload payload) { - - /*-------------------------------------------------------------------------------------------------------------------------- - | Skip for obvious reasons - \-------------------------------------------------------------------------------------------------------------------------*/ - if (Resolver is null || IsNew) { - return; - } - - /*-------------------------------------------------------------------------------------------------------------------------- - | Filter to payload that are not yet loaded - \-------------------------------------------------------------------------------------------------------------------------*/ - payload = FilterPayload(payload); - - if (payload is TopicPayload.None) { - return; - } - - // Ensure the appropriate payload are loaded - Resolver.EnsureLoaded(this, payload); - - } - - /// - /// - /// One or more flags identifying the payload that should be ensured to be loaded. - /// /// An optional token that can be used to cancel the operation. - public Task EnsureLoadedAsync(TopicPayload payload, CancellationToken cancellationToken = default) { + public Task EnsureLoaded(TopicPayload payload, CancellationToken cancellationToken = default) { /*-------------------------------------------------------------------------------------------------------------------------- | Skip for obvious reasons @@ -328,7 +300,7 @@ public Task EnsureLoadedAsync(TopicPayload payload, CancellationToken cancellati } // Ensure the appropriate payload are loaded - return Resolver.EnsureLoadedAsync(this, payload, cancellationToken); + return Resolver.EnsureLoaded(this, payload, cancellationToken); } @@ -953,7 +925,7 @@ public Topic? DerivedTopic { public TopicRelationshipMultiMap Relationships { get { if (_relationships.LoadState is LoadState.NotLoaded && Resolver is not null) { - Resolver.EnsureLoaded(this, TopicPayload.Relationships); + EnsureLoaded(TopicPayload.Relationships).GetAwaiter().GetResult(); _relationships.Deferred.Clear(); } return _relationships; @@ -974,7 +946,7 @@ public TopicRelationshipMultiMap Relationships { public TopicReferenceCollection References { get { if (_references.LoadState is LoadState.NotLoaded && Resolver is not null) { - Resolver.EnsureLoaded(this, TopicPayload.References); + EnsureLoaded(TopicPayload.References).GetAwaiter().GetResult(); _references.Deferred.Clear(); } return _references; From caab55a238278d4e06dad5179b42be56cf2cd4e8 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Wed, 8 Jul 2026 16:49:32 -0700 Subject: [PATCH 113/337] Move `Save()`, `Move()`, `Delete()`, &c to `async` Following the lead of `Load()`, moved `Save()` (and `SaveTopic()`), `Move()` (and `MoveTopic()`), `Delete()` (and `DeleteTopic()`), as well as `Rollback()` and `Refresh()` from synchronous to asynchronous. The benefit of this won't be as strong as with `Load()` in most cases, but it's more consistent and, since these are typically called from controllers, will be compatible with their existing call structure. This is tangentially related to #111. --- .../SampleActivator.cs | 2 +- .../Repositories/StubTopicRepository.cs | 8 +- OnTopic.Data.Sql/SqlTopicRepository.cs | 40 ++++---- OnTopic.TestDoubles/DummyTopicRepository.cs | 10 +- OnTopic.TestDoubles/StubTopicRepository.cs | 10 +- .../ReverseTopicMappingServiceTest.cs | 2 +- OnTopic.Tests/TopicQueryingTest.cs | 8 +- OnTopic.Tests/TopicRepositoryBaseTest.cs | 92 +++++++++---------- OnTopic/Repositories/ITopicRepository.cs | 11 +-- .../Repositories/ObservableTopicRepository.cs | 10 +- OnTopic/Repositories/TopicRepository.cs | 36 ++++---- .../Repositories/TopicRepositoryDecorator.cs | 12 +-- 12 files changed, 121 insertions(+), 120 deletions(-) diff --git a/OnTopic.AspNetCore.Mvc.Host/SampleActivator.cs b/OnTopic.AspNetCore.Mvc.Host/SampleActivator.cs index 4657d71d..9a4263ae 100644 --- a/OnTopic.AspNetCore.Mvc.Host/SampleActivator.cs +++ b/OnTopic.AspNetCore.Mvc.Host/SampleActivator.cs @@ -111,7 +111,7 @@ public object Create(ControllerContext context) { \-------------------------------------------------------------------------------------------------------------------------*/ if (DateTime.UtcNow > _cacheLastUpdated.AddMinutes(1)) { var currentUpdate = DateTime.UtcNow; - _topicRepository.Refresh(_topicRepository.Load().GetAwaiter().GetResult()!, _cacheLastUpdated); + _topicRepository.Refresh(_topicRepository.Load().GetAwaiter().GetResult()!, _cacheLastUpdated).GetAwaiter().GetResult(); _cacheLastUpdated = currentUpdate; } diff --git a/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/Repositories/StubTopicRepository.cs b/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/Repositories/StubTopicRepository.cs index a9781add..e15c4aa7 100644 --- a/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/Repositories/StubTopicRepository.cs +++ b/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/Repositories/StubTopicRepository.cs @@ -114,28 +114,28 @@ public StubTopicRepository() : base() { | METHOD: REFRESH \---------------------------------------------------------------------------------------------------------------------------*/ /// - public override void Refresh(Topic referenceTopic, DateTime since) => + public override Task Refresh(Topic referenceTopic, DateTime since) => throw new NotImplementedException(); /*============================================================================================================================ | METHOD: SAVE \---------------------------------------------------------------------------------------------------------------------------*/ /// - protected override void SaveTopic([NotNull]Topic topic, DateTime version, bool persistRelationships) => + protected override Task SaveTopic([NotNull]Topic topic, DateTime version, bool persistRelationships) => throw new NotImplementedException(); /*============================================================================================================================ | METHOD: MOVE \---------------------------------------------------------------------------------------------------------------------------*/ /// - protected override void MoveTopic(Topic topic, Topic target, Topic? sibling = null) => + protected override Task MoveTopic(Topic topic, Topic target, Topic? sibling = null) => throw new NotImplementedException(); /*============================================================================================================================ | METHOD: DELETE \---------------------------------------------------------------------------------------------------------------------------*/ /// - protected override void DeleteTopic(Topic topic) => + protected override Task DeleteTopic(Topic topic) => throw new NotImplementedException(); /*============================================================================================================================ diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index 5a504e53..da396d79 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -328,7 +328,7 @@ public SqlTopicRepository(string connectionString) : base() { | METHOD: REFRESH \---------------------------------------------------------------------------------------------------------------------------*/ /// - public override void Refresh(Topic referenceTopic, DateTime since) { + public override async Task Refresh(Topic referenceTopic, DateTime since) { /*-------------------------------------------------------------------------------------------------------------------------- | Normalize parameters @@ -364,9 +364,9 @@ public override void Refresh(Topic referenceTopic, DateTime since) { | Process database query \-------------------------------------------------------------------------------------------------------------------------*/ try { - connection.Open(); - using var reader = command.ExecuteReader(); - reader.LoadTopicGraphAsync(-1, referenceTopic.GetRootTopic(), false).GetAwaiter().GetResult(); + await connection.OpenAsync().ConfigureAwait(false); + using var reader = (SqlDataReader)await command.ExecuteReaderAsync().ConfigureAwait(false); + await reader.LoadTopicGraphAsync(-1, referenceTopic.GetRootTopic(), false).ConfigureAwait(false); } /*-------------------------------------------------------------------------------------------------------------------------- @@ -498,7 +498,7 @@ public virtual async Task EnsureLoaded(Topic topic, TopicPayload payload, Cancel | METHOD: SAVE \---------------------------------------------------------------------------------------------------------------------------*/ /// - protected override sealed void SaveTopic( + protected override sealed async Task SaveTopic( [NotNull]Topic topic, DateTime version, bool persistRelationships @@ -530,7 +530,7 @@ bool persistRelationships \-------------------------------------------------------------------------------------------------------------------------*/ if (!extendedBoundaryLoaded) { if (extendedAttributeList.Any(a => a.IsDirty)) { - EnsureLoaded(topic, TopicPayload.ExtendedAttributes).GetAwaiter().GetResult(); + await EnsureLoaded(topic, TopicPayload.ExtendedAttributes).ConfigureAwait(false); extendedBoundaryLoaded = true; extendedAttributeList = GetAttributes(topic, isExtendedAttribute: true).ToList(); } @@ -619,7 +619,7 @@ bool persistRelationships using var connection = new SqlConnection(_connectionString); var procedureName = topic.IsNew? "CreateTopic" : "UpdateTopic"; - connection.Open(); + await connection.OpenAsync().ConfigureAwait(false); using var command = new SqlCommand(procedureName, connection) { CommandType = CommandType.StoredProcedure @@ -654,7 +654,7 @@ bool persistRelationships try { if (topic.IsNew || isTopicDirty || areAttributesDirty) { - command.ExecuteNonQuery(); + await command.ExecuteNonQueryAsync().ConfigureAwait(false); topic.Id = command.GetReturnCode(); } @@ -664,11 +664,11 @@ bool persistRelationships ); if (persistRelationships && areRelationshipsDirty) { - PersistRelationships(topic, version, connection); + await PersistRelationships(topic, version, connection).ConfigureAwait(false); } if (persistRelationships && areReferencesDirty) { - PersistReferences(topic, version, connection); + await PersistReferences(topic, version, connection).ConfigureAwait(false); } } @@ -696,7 +696,7 @@ bool persistRelationships | METHOD: MOVE TOPIC \---------------------------------------------------------------------------------------------------------------------------*/ /// - protected override sealed void MoveTopic(Topic topic, Topic target, Topic? sibling) { + protected override sealed async Task MoveTopic(Topic topic, Topic target, Topic? sibling) { /*-------------------------------------------------------------------------------------------------------------------------- | Validate parameters @@ -727,8 +727,8 @@ protected override sealed void MoveTopic(Topic topic, Topic target, Topic? sibli | Process database query \-------------------------------------------------------------------------------------------------------------------------*/ try { - connection.Open(); - command.ExecuteNonQuery(); + await connection.OpenAsync().ConfigureAwait(false); + await command.ExecuteNonQueryAsync().ConfigureAwait(false); } /*-------------------------------------------------------------------------------------------------------------------------- @@ -747,7 +747,7 @@ protected override sealed void MoveTopic(Topic topic, Topic target, Topic? sibli | METHOD: DELETE TOPIC \---------------------------------------------------------------------------------------------------------------------------*/ /// - protected override sealed void DeleteTopic(Topic topic) { + protected override sealed async Task DeleteTopic(Topic topic) { /*-------------------------------------------------------------------------------------------------------------------------- | Validate parameters @@ -771,8 +771,8 @@ protected override sealed void DeleteTopic(Topic topic) { | Process database query \-------------------------------------------------------------------------------------------------------------------------*/ try { - connection.Open(); - command.ExecuteNonQuery(); + await connection.OpenAsync().ConfigureAwait(false); + await command.ExecuteNonQueryAsync().ConfigureAwait(false); } /*-------------------------------------------------------------------------------------------------------------------------- @@ -830,7 +830,7 @@ private static void AddEnsureLoadedParameters(SqlCommand command, int topicId, T /// The topic object whose relationships should be persisted. /// The version that should be associated with the updated value. /// The SQL connection. - private static void PersistRelationships(Topic topic, DateTime version, SqlConnection connection) { + private static async Task PersistRelationships(Topic topic, DateTime version, SqlConnection connection) { var rawTopic = (ITopicBackingAccessor)topic; @@ -867,7 +867,7 @@ private static void PersistRelationships(Topic topic, DateTime version, SqlConne command.AddParameter("Version", version); command.AddParameter("DeleteUnmatched", rawTopic.Relationships.LoadState is LoadState.Loaded); - command.ExecuteNonQuery(); + await command.ExecuteNonQueryAsync().ConfigureAwait(false); } @@ -899,7 +899,7 @@ private static void PersistRelationships(Topic topic, DateTime version, SqlConne /// The topic object whose references should be persisted. /// The version that should be associated with the updated value. /// The SQL connection. - private static void PersistReferences(Topic topic, DateTime version, SqlConnection connection) { + private static async Task PersistReferences(Topic topic, DateTime version, SqlConnection connection) { var rawTopic = (ITopicBackingAccessor)topic; @@ -925,7 +925,7 @@ private static void PersistReferences(Topic topic, DateTime version, SqlConnecti command.AddParameter("Version", version); command.AddParameter("DeleteUnmatched", rawTopic.References.LoadState is LoadState.Loaded); - command.ExecuteNonQuery(); + await command.ExecuteNonQueryAsync().ConfigureAwait(false); } diff --git a/OnTopic.TestDoubles/DummyTopicRepository.cs b/OnTopic.TestDoubles/DummyTopicRepository.cs index bda2d3fb..4d382b20 100644 --- a/OnTopic.TestDoubles/DummyTopicRepository.cs +++ b/OnTopic.TestDoubles/DummyTopicRepository.cs @@ -61,30 +61,30 @@ public DummyTopicRepository() : base() { } | METHOD: ROLLBACK \---------------------------------------------------------------------------------------------------------------------------*/ /// - public override void Rollback(Topic topic, DateTime version) => throw new NotImplementedException(); + public override Task Rollback(Topic topic, DateTime version) => throw new NotImplementedException(); /*============================================================================================================================ | METHOD: REFRESH \---------------------------------------------------------------------------------------------------------------------------*/ /// - public override void Refresh(Topic referenceTopic, DateTime since) => throw new NotImplementedException(); + public override Task Refresh(Topic referenceTopic, DateTime since) => throw new NotImplementedException(); /*============================================================================================================================ | METHOD: SAVE \---------------------------------------------------------------------------------------------------------------------------*/ /// - public override void Save(Topic topic, bool isRecursive = false) => throw new NotImplementedException(); + public override Task Save(Topic topic, bool isRecursive = false) => throw new NotImplementedException(); /*============================================================================================================================ | METHOD: MOVE \---------------------------------------------------------------------------------------------------------------------------*/ /// - public override void Move(Topic topic, Topic target, Topic? sibling = null) => throw new NotImplementedException(); + public override Task Move(Topic topic, Topic target, Topic? sibling = null) => throw new NotImplementedException(); /*============================================================================================================================ | METHOD: DELETE \---------------------------------------------------------------------------------------------------------------------------*/ /// - public override void Delete(Topic topic, bool isRecursive = false) => throw new NotImplementedException(); + public override Task Delete(Topic topic, bool isRecursive = false) => throw new NotImplementedException(); } //Class \ No newline at end of file diff --git a/OnTopic.TestDoubles/StubTopicRepository.cs b/OnTopic.TestDoubles/StubTopicRepository.cs index 74013a87..2035f453 100644 --- a/OnTopic.TestDoubles/StubTopicRepository.cs +++ b/OnTopic.TestDoubles/StubTopicRepository.cs @@ -181,13 +181,13 @@ public StubTopicRepository() : base() { | METHOD: REFRESH \---------------------------------------------------------------------------------------------------------------------------*/ /// - public override void Refresh(Topic referenceTopic, DateTime since) { } + public override Task Refresh(Topic referenceTopic, DateTime since) => Task.CompletedTask; /*============================================================================================================================ | METHOD: SAVE \---------------------------------------------------------------------------------------------------------------------------*/ /// - protected override void SaveTopic([NotNull]Topic topic, DateTime version, bool persistRelationships) { + protected override Task SaveTopic([NotNull]Topic topic, DateTime version, bool persistRelationships) { /*-------------------------------------------------------------------------------------------------------------------------- | Assign faux identity @@ -196,6 +196,8 @@ protected override void SaveTopic([NotNull]Topic topic, DateTime version, bool p topic.Id = _identity++; } + return Task.CompletedTask; + } /*============================================================================================================================ @@ -237,13 +239,13 @@ public virtual Task EnsureLoaded(Topic topic, TopicPayload payload, Cancellation | METHOD: MOVE \---------------------------------------------------------------------------------------------------------------------------*/ /// - protected override void MoveTopic(Topic topic, Topic target, Topic? sibling = null) { } + protected override Task MoveTopic(Topic topic, Topic target, Topic? sibling = null) => Task.CompletedTask; /*============================================================================================================================ | METHOD: DELETE \---------------------------------------------------------------------------------------------------------------------------*/ /// - protected override void DeleteTopic(Topic topic) { } + protected override Task DeleteTopic(Topic topic) => Task.CompletedTask; /*============================================================================================================================ | METHOD: GET ATTRIBUTES (PROXY) diff --git a/OnTopic.Tests/ReverseTopicMappingServiceTest.cs b/OnTopic.Tests/ReverseTopicMappingServiceTest.cs index 42bbe014..2b6cced8 100644 --- a/OnTopic.Tests/ReverseTopicMappingServiceTest.cs +++ b/OnTopic.Tests/ReverseTopicMappingServiceTest.cs @@ -261,7 +261,7 @@ public async Task Map_Relationships_ReturnsMappedTopic() { Assert.False(target?.PermittedContentTypes.Contains(contentTypes[3])); //Revert state - _topicRepository.Delete(topic); + await _topicRepository.Delete(topic); } diff --git a/OnTopic.Tests/TopicQueryingTest.cs b/OnTopic.Tests/TopicQueryingTest.cs index 23cabb8c..16855742 100644 --- a/OnTopic.Tests/TopicQueryingTest.cs +++ b/OnTopic.Tests/TopicQueryingTest.cs @@ -241,7 +241,7 @@ public void GetContentType_ValidContentType_ReturnsContentType() { /// /> returns null. /// [Fact] - public void GetContentType_InvalidContentType_ReturnsNull() { + public async Task GetContentType_InvalidContentType_ReturnsNull() { var parentTopic = _topicRepository.Load(11111).GetAwaiter().GetResult(); var topic = new Topic("Test", "NonExistent", parentTopic); @@ -250,7 +250,7 @@ public void GetContentType_InvalidContentType_ReturnsNull() { Assert.Null(contentTypeDescriptor); //Revert state - _topicRepository.Delete(topic); + await _topicRepository.Delete(topic); } @@ -266,7 +266,7 @@ public void GetContentType_InvalidContentType_ReturnsNull() { /// Topic"/> which doesn't derive from . /// [Fact] - public void GetContentType_InvalidType_ReturnsNull() { + public async Task GetContentType_InvalidType_ReturnsNull() { var parentTopic = _topicRepository.Load(11111).GetAwaiter().GetResult(); var topic = new Topic("Test", "Title", parentTopic); @@ -275,7 +275,7 @@ public void GetContentType_InvalidType_ReturnsNull() { Assert.Null(contentTypeDescriptor); //Revert state - _topicRepository.Delete(topic); + await _topicRepository.Delete(topic); } diff --git a/OnTopic.Tests/TopicRepositoryBaseTest.cs b/OnTopic.Tests/TopicRepositoryBaseTest.cs index d6170ebe..2dbe1fa9 100644 --- a/OnTopic.Tests/TopicRepositoryBaseTest.cs +++ b/OnTopic.Tests/TopicRepositoryBaseTest.cs @@ -147,14 +147,14 @@ public void Load_ValidDate_ReturnsTopic() { /// "Topic.LastModified"/> value is updated. /// [Fact] - public void Rollback_Topic_UpdatesLastModified() { + public async Task Rollback_Topic_UpdatesLastModified() { var version = DateTime.UtcNow.AddDays(-1); var topic = _topicRepository.Load(11111).GetAwaiter().GetResult(); if (topic is not null) { topic.VersionHistory.Add(version); - _topicRepository.Rollback(topic, version); + await _topicRepository.Rollback(topic, version); } Assert.True(topic?.VersionHistory.Contains(version)); @@ -195,7 +195,7 @@ await Assert.ThrowsAsync(() => /// Deletes a topic which other topics, outside the graph, derive from. Expects exception. /// [Fact] - public void Delete_BaseTopic_ThrowsException() { + public async Task Delete_BaseTopic_ThrowsException() { var root = new Topic("Root", "Page"); var topic = new Topic("Topic", "Page", root); @@ -204,7 +204,7 @@ public void Delete_BaseTopic_ThrowsException() { BaseTopic = child }; - Assert.Throws(() => + await Assert.ThrowsAsync(() => _topicRepository.Delete(topic, true) ); @@ -217,7 +217,7 @@ public void Delete_BaseTopic_ThrowsException() { /// Deletes a topic which another topic within the graph derives from. Expects success. /// [Fact] - public void Delete_InternallyDerivedTopic_Succeeds() { + public async Task Delete_InternallyDerivedTopic_Succeeds() { var root = new Topic("Root", "Page"); var topic = new Topic("Topic", "Page", root); @@ -226,7 +226,7 @@ public void Delete_InternallyDerivedTopic_Succeeds() { BaseTopic = child }; - _topicRepository.Delete(topic, true); + await _topicRepository.Delete(topic, true); Assert.Empty(root.Children); @@ -239,12 +239,12 @@ public void Delete_InternallyDerivedTopic_Succeeds() { /// Deletes a topic with descendant topics. Expects exception if isRecursive is set to false. /// [Fact] - public void Delete_Descendants_ThrowsException() { + public async Task Delete_Descendants_ThrowsException() { var topic = new Topic("Topic", "Page"); _ = new Topic("Child", "Page", topic); - Assert.Throws(() => + await Assert.ThrowsAsync(() => _topicRepository.Delete(topic) ); @@ -257,13 +257,13 @@ public void Delete_Descendants_ThrowsException() { /// Deletes a topic with descendant topics. Expects no exception if isRecursive is set to true. /// [Fact] - public void Delete_DescendantsWithRecursive_Succeeds() { + public async Task Delete_DescendantsWithRecursive_Succeeds() { var root = new Topic("Root", "Page"); var topic = new Topic("Topic", "Page", root); _ = new Topic("Child", "Page", topic); - _topicRepository.Delete(topic, true); + await _topicRepository.Delete(topic, true); Assert.Empty(root.Children); @@ -276,13 +276,13 @@ public void Delete_DescendantsWithRecursive_Succeeds() { /// Deletes a topic with nested topics. Expects no exception, even if isRecursive is set to false. /// [Fact] - public void Delete_NestedTopics_Succeeds() { + public async Task Delete_NestedTopics_Succeeds() { var root = new Topic("Root", "Page"); var topic = new Topic("Topic", "Page", root); _ = new Topic("Child", "List", topic); - _topicRepository.Delete(topic); + await _topicRepository.Delete(topic); Assert.Empty(root.Children); @@ -296,7 +296,7 @@ public void Delete_NestedTopics_Succeeds() { /// target topics' collection. /// [Fact] - public void Delete_Relationships_DeleteRelationships() { + public async Task Delete_Relationships_DeleteRelationships() { var root = new Topic("Root", "Page"); var topic = new Topic("Topic", "Page", root); @@ -306,7 +306,7 @@ public void Delete_Relationships_DeleteRelationships() { child.Relationships.SetValue("Related", associated); child.References.SetValue("Referenced", associated); - _topicRepository.Delete(topic, true); + await _topicRepository.Delete(topic, true); Assert.Empty(associated.IncomingRelationships.GetValues("Related")); Assert.Empty(associated.IncomingRelationships.GetValues("Referenced")); @@ -320,7 +320,7 @@ public void Delete_Relationships_DeleteRelationships() { /// Deletes a topic with incoming relationships. Deletes the relationships or references from the associated topic. /// [Fact] - public void Delete_IncomingRelationships_DeleteAssociations() { + public async Task Delete_IncomingRelationships_DeleteAssociations() { var root = new Topic("Root", "Page"); var topic = new Topic("Topic", "Page", root); @@ -331,7 +331,7 @@ public void Delete_IncomingRelationships_DeleteAssociations() { source1.Relationships.SetValue("Associations", child); source2.References.SetValue("Associations", child); - _topicRepository.Delete(topic, true); + await _topicRepository.Delete(topic, true); Assert.Empty(source1.Relationships.GetValues("Associations")); @@ -682,13 +682,13 @@ public void GetContentTypeDescriptor_GetNewContentType_ReturnsFromTopicGraph() { /// typically only occur when initializing a new database, and is an unexpected condition. /// [Fact] - public void GetContentTypeDescriptor_MissingRootContentType_ReturnsNull() { + public async Task GetContentTypeDescriptor_MissingRootContentType_ReturnsNull() { var topicRepository = new StubTopicRepository(); var configuration = topicRepository.Load("Root:Configuration").GetAwaiter().GetResult(); var topic = new Topic("Test", "Page"); - topicRepository.Delete(configuration!, true); + await topicRepository.Delete(configuration!, true); var contentType = topicRepository.GetContentTypeDescriptorProxy(topic); @@ -721,12 +721,12 @@ public void GetContentTypeDescriptor_GetInvalidContentType_ReturnsNull() { /// immediately reflected in the cache of s. /// [Fact] - public void Save_ContentTypeDescriptor_UpdatesContentTypeCache() { + public async Task Save_ContentTypeDescriptor_UpdatesContentTypeCache() { var contentTypes = _topicRepository.GetContentTypeDescriptors(); var topic = new ContentTypeDescriptor("NewContentType", "ContentTypeDescriptor"); - _topicRepository.Save(topic); + await _topicRepository.Save(topic); Assert.Contains(topic, contentTypes); @@ -741,7 +741,7 @@ public void Save_ContentTypeDescriptor_UpdatesContentTypeCache() { /// it the cache is updated. /// [Fact] - public void Save_ContentTypeDescriptor_UpdatesPermittedContentTypes() { + public async Task Save_ContentTypeDescriptor_UpdatesPermittedContentTypes() { var contentTypes = _topicRepository.GetContentTypeDescriptors(); var contentTypesRoot = contentTypes.GetValue("ContentTypes"); @@ -756,7 +756,7 @@ public void Save_ContentTypeDescriptor_UpdatesPermittedContentTypes() { pageContentType.Relationships.SetValue("ContentTypes", lookupContentType); - _topicRepository.Save(contentTypesRoot, true); + await _topicRepository.Save(contentTypesRoot, true); Assert.NotEqual(initialCount, pageContentType.PermittedContentTypes.Count); @@ -770,12 +770,12 @@ public void Save_ContentTypeDescriptor_UpdatesPermittedContentTypes() { /// new version. /// [Fact] - public void Save_NewTopic_UpdatesVersionHistory() { + public async Task Save_NewTopic_UpdatesVersionHistory() { var parent = _topicRepository.Load("Root:Web:Web_3:Web_3_0").GetAwaiter().GetResult(); var topic = new Topic("Test", "Page", parent); - _topicRepository.Save(topic); + await _topicRepository.Save(topic); Assert.True(topic.VersionHistory.Count > 0); @@ -789,13 +789,13 @@ public void Save_NewTopic_UpdatesVersionHistory() { /// child is correctly updated. /// [Fact] - public void Save_IsRecursive_SavesChild() { + public async Task Save_IsRecursive_SavesChild() { var parent = _topicRepository.Load("Root:Web:Web_3:Web_3_0").GetAwaiter().GetResult(); var topic = new Topic("Test", "Page", parent); var child = new Topic("Child", "Page", topic); - _topicRepository.Save(topic, true); + await _topicRepository.Save(topic, true); Assert.False(child.IsNew); @@ -810,7 +810,7 @@ public void Save_IsRecursive_SavesChild() { /// "TrackedRecordCollection{TItem,TValue, TAttribute}.IsDirty()"/> as false. /// [Fact] - public void Save_UnresolvedReference_Resolves() { + public async Task Save_UnresolvedReference_Resolves() { var parent = _topicRepository.Load("Root:Web:Web_3:Web_3_0").GetAwaiter().GetResult(); var topic = new Topic("Test", "Page", parent); @@ -818,7 +818,7 @@ public void Save_UnresolvedReference_Resolves() { topic.References.SetValue("Test", reference); - _topicRepository.Save(topic, true); + await _topicRepository.Save(topic, true); } @@ -830,7 +830,7 @@ public void Save_UnresolvedReference_Resolves() { /// expected if that reference cannot be resolved. /// [Fact] - public void Save_UnresolvedReference_ThrowsException() { + public async Task Save_UnresolvedReference_ThrowsException() { var parent = _topicRepository.Load("Root:Web:Web_3:Web_3_0").GetAwaiter().GetResult(); var topic = new Topic("Test", "Page", parent); @@ -838,7 +838,7 @@ public void Save_UnresolvedReference_ThrowsException() { topic.References.SetValue("Test", reference); - Assert.Throws(() => + await Assert.ThrowsAsync(() => _topicRepository.Save(topic, true) ); @@ -852,8 +852,8 @@ public void Save_UnresolvedReference_ThrowsException() { /// expected . /// [Fact] - public void Save_InvalidContentType_ThrowsException() => - Assert.Throws(() => + public async Task Save_InvalidContentType_ThrowsException() => + await Assert.ThrowsAsync(() => _topicRepository.Save(new("Test", "InvalidContentType")) ); @@ -866,14 +866,14 @@ public void Save_InvalidContentType_ThrowsException() => /// is immediately reflected in the cache of s. /// [Fact] - public void Delete_ContentTypeDescriptor_UpdatesContentTypeCache() { + public async Task Delete_ContentTypeDescriptor_UpdatesContentTypeCache() { var contentTypes = _topicRepository.GetContentTypeDescriptors(); var contentType = contentTypes.Contains("Page")? contentTypes["Page"] : null; Contract.Assume(contentType); - _topicRepository.Delete(contentType); + await _topicRepository.Delete(contentType); Assert.DoesNotContain(contentType, contentTypes); @@ -886,7 +886,7 @@ public void Delete_ContentTypeDescriptor_UpdatesContentTypeCache() { /// Moves a after a sibling in another parent, and ensures it is set correctly. /// [Fact] - public void Move_AfterSibling_SetCorrectly() { + public async Task Move_AfterSibling_SetCorrectly() { var source = new Topic("Source", "Page"); var topic = new Topic("Test", "Page", source); @@ -894,7 +894,7 @@ public void Move_AfterSibling_SetCorrectly() { var sibling = new Topic("Sibling", "Page", target); var olderSibling = new Topic("OlderSibling", "Page", target); - _topicRepository.Move(topic, target, sibling); + await _topicRepository.Move(topic, target, sibling); Assert.Equal(target, topic.Parent); Assert.Equal(0, target.Children.IndexOf(sibling)); @@ -913,7 +913,7 @@ public void Move_AfterSibling_SetCorrectly() { /// cref="ContentTypeDescriptor"/>s. /// [Fact] - public void Move_ContentTypeDescriptor_UpdatesContentTypeCache() { + public async Task Move_ContentTypeDescriptor_UpdatesContentTypeCache() { var contentTypes = _topicRepository.GetContentTypeDescriptors(); var pageContentType = contentTypes.Contains("Page")? contentTypes["Page"] : null; @@ -923,7 +923,7 @@ public void Move_ContentTypeDescriptor_UpdatesContentTypeCache() { Contract.Assume(contactContentType); Contract.Assume(pageContentType); - _topicRepository.Move(contactContentType, pageContentType); + await _topicRepository.Move(contactContentType, pageContentType); Assert.NotEqual(contactContentType.AttributeDescriptors.Count, contactAttributeCount); @@ -938,7 +938,7 @@ public void Move_ContentTypeDescriptor_UpdatesContentTypeCache() { /// of the child reflects the change. /// [Fact] - public void Save_AttributeDescriptor_UpdatesContentType() { + public async Task Save_AttributeDescriptor_UpdatesContentType() { var contentType = new ContentTypeDescriptor("Parent", "ContentTypeDescriptor", null, 1); var attributeList = new Topic("Attributes", "List", contentType, 2); @@ -952,7 +952,7 @@ public void Save_AttributeDescriptor_UpdatesContentType() { Contract.Assume(newAttribute); - _topicRepository.Save(newAttribute); + await _topicRepository.Save(newAttribute); Assert.Equal(attributeCount+1, childContentType.AttributeDescriptors.Count); @@ -967,7 +967,7 @@ public void Save_AttributeDescriptor_UpdatesContentType() { /// cref="ContentTypeDescriptor.AttributeDescriptors"/> of the child reflects the change. /// [Fact] - public void Delete_AttributeDescriptor_UpdatesContentTypeCache() { + public async Task Delete_AttributeDescriptor_UpdatesContentTypeCache() { var contentType = new ContentTypeDescriptor("Parent", "ContentTypeDescriptor"); var attributeList = new Topic("Attributes", "List", contentType); @@ -979,7 +979,7 @@ public void Delete_AttributeDescriptor_UpdatesContentTypeCache() { var attributeCount = childContentType.AttributeDescriptors.Count; - _topicRepository.Delete(newAttribute); + await _topicRepository.Delete(newAttribute); Assert.True(childContentType.AttributeDescriptors.Count < attributeCount); @@ -1143,12 +1143,12 @@ public void Save_TopicMovedEvent_IsRaised() { /// that deferred boundaries can be populated on demand after the save. /// [Fact] - public void Save_NewTopic_StampsResolver() { + public async Task Save_NewTopic_StampsResolver() { var parent = _topicRepository.Load("Root:Web:Web_3:Web_3_0").GetAwaiter().GetResult(); var topic = new Topic("Test", "Page", parent); - _topicRepository.Save(topic); + await _topicRepository.Save(topic); Assert.NotNull(topic.Resolver); @@ -1163,14 +1163,14 @@ public void Save_NewTopic_StampsResolver() { /// "Topic.IsLoaded(TopicPayload)"/>, so a not-loaded children collection prevents descent. /// [Fact] - public void Save_NotLoadedChildren_SkipsRecursiveDescent() { + public async Task Save_NotLoadedChildren_SkipsRecursiveDescent() { var parent = new Topic("Parent", "Page"); var child = new Topic("Child", "Page", parent); parent.Children.LoadState = LoadState.NotLoaded; - _topicRepository.Save(parent, isRecursive: true); + await _topicRepository.Save(parent, isRecursive: true); Assert.True(child.IsNew); diff --git a/OnTopic/Repositories/ITopicRepository.cs b/OnTopic/Repositories/ITopicRepository.cs index e5322144..17b9965f 100644 --- a/OnTopic/Repositories/ITopicRepository.cs +++ b/OnTopic/Repositories/ITopicRepository.cs @@ -173,7 +173,7 @@ public interface ITopicRepository { /// exception="T:System.ArgumentNullException"> /// !VersionHistory.Contains(version) /// - void Rollback(Topic topic, DateTime version); + Task Rollback(Topic topic, DateTime version); /*============================================================================================================================ | METHOD: REFRESH @@ -187,7 +187,7 @@ public interface ITopicRepository { /// indexed attributes, extended attributes, relationships, and topic references. It is not expected to handle deletes /// or reordering of topics. /// - void Refresh(Topic referenceTopic, DateTime since); + Task Refresh(Topic referenceTopic, DateTime since); /*============================================================================================================================ | METHOD: SAVE @@ -203,7 +203,7 @@ public interface ITopicRepository { /// topic is not null /// /// topic - void Save(Topic topic, bool isRecursive = false); + Task Save(Topic topic, bool isRecursive = false); /// [ExcludeFromCodeCoverage] @@ -227,13 +227,12 @@ public interface ITopicRepository { /// An optional object representing a sibling adjacent to which the source should /// be moved. /// - /// Boolean value representing whether the operation completed successfully. /// /// topic is not null /// - void Move(Topic topic, Topic target, Topic? sibling = null); + Task Move(Topic topic, Topic target, Topic? sibling = null); /*============================================================================================================================ | METHOD: DELETE @@ -250,6 +249,6 @@ public interface ITopicRepository { /// topic is not null /// /// topic - void Delete(Topic topic, bool isRecursive = false); + Task Delete(Topic topic, bool isRecursive = false); } //Interface \ No newline at end of file diff --git a/OnTopic/Repositories/ObservableTopicRepository.cs b/OnTopic/Repositories/ObservableTopicRepository.cs index 81ee4f59..683d7ba5 100644 --- a/OnTopic/Repositories/ObservableTopicRepository.cs +++ b/OnTopic/Repositories/ObservableTopicRepository.cs @@ -242,19 +242,19 @@ public event EventHandler? TopicRenamed { | METHOD: REFRESH \---------------------------------------------------------------------------------------------------------------------------*/ /// - public abstract void Refresh(Topic referenceTopic, DateTime since); + public abstract Task Refresh(Topic referenceTopic, DateTime since); /*============================================================================================================================ | METHOD: ROLLBACK \---------------------------------------------------------------------------------------------------------------------------*/ /// - public abstract void Rollback(Topic topic, DateTime version); + public abstract Task Rollback(Topic topic, DateTime version); /*============================================================================================================================ | METHOD: SAVE \---------------------------------------------------------------------------------------------------------------------------*/ /// - public abstract void Save(Topic topic, bool isRecursive = false); + public abstract Task Save(Topic topic, bool isRecursive = false); /// [ExcludeFromCodeCoverage] @@ -265,13 +265,13 @@ public event EventHandler? TopicRenamed { | METHOD: MOVE \---------------------------------------------------------------------------------------------------------------------------*/ /// - public abstract void Move(Topic topic, Topic target, Topic? sibling = null); + public abstract Task Move(Topic topic, Topic target, Topic? sibling = null); /*============================================================================================================================ | METHOD: DELETE \---------------------------------------------------------------------------------------------------------------------------*/ /// - public abstract void Delete(Topic topic, bool isRecursive = false); + public abstract Task Delete(Topic topic, bool isRecursive = false); /*============================================================================================================================ | METHOD: STAMP RESOLVER diff --git a/OnTopic/Repositories/TopicRepository.cs b/OnTopic/Repositories/TopicRepository.cs index 1388421e..830130a6 100644 --- a/OnTopic/Repositories/TopicRepository.cs +++ b/OnTopic/Repositories/TopicRepository.cs @@ -232,7 +232,7 @@ protected ContentTypeDescriptorCollection SetContentTypeDescriptors(ContentTypeD | METHOD: ROLLBACK \---------------------------------------------------------------------------------------------------------------------------*/ /// - public override void Rollback([ValidatedNotNull]Topic topic, DateTime version) { + public override async Task Rollback([ValidatedNotNull]Topic topic, DateTime version) { /*-------------------------------------------------------------------------------------------------------------------------- | Validate parameters @@ -247,12 +247,12 @@ public override void Rollback([ValidatedNotNull]Topic topic, DateTime version) { /*-------------------------------------------------------------------------------------------------------------------------- | Retrieve topic from database \-------------------------------------------------------------------------------------------------------------------------*/ - Load(topic, version); + await Load(topic, version).ConfigureAwait(false); /*-------------------------------------------------------------------------------------------------------------------------- | Save as new version \-------------------------------------------------------------------------------------------------------------------------*/ - Save(topic, false); + await Save(topic, false).ConfigureAwait(false); } @@ -260,7 +260,7 @@ public override void Rollback([ValidatedNotNull]Topic topic, DateTime version) { | METHOD: SAVE \---------------------------------------------------------------------------------------------------------------------------*/ /// - public override sealed void Save([ValidatedNotNull] Topic topic, bool isRecursive = false) { + public override sealed async Task Save([ValidatedNotNull] Topic topic, bool isRecursive = false) { /*-------------------------------------------------------------------------------------------------------------------------- | Establish parameters @@ -281,14 +281,14 @@ public override sealed void Save([ValidatedNotNull] Topic topic, bool isRecurs /*-------------------------------------------------------------------------------------------------------------------------- | Handle first pass \-------------------------------------------------------------------------------------------------------------------------*/ - Save(topic, isRecursive, unresolvedTopics, version); + await Save(topic, isRecursive, unresolvedTopics, version).ConfigureAwait(false); /*-------------------------------------------------------------------------------------------------------------------------- | Attempt to resolve outstanding associations \-------------------------------------------------------------------------------------------------------------------------*/ foreach (var unresolvedTopic in unresolvedTopics.ToList()) { unresolvedTopics.Remove(unresolvedTopic); - Save(unresolvedTopic, false, unresolvedTopics, version); + await Save(unresolvedTopic, false, unresolvedTopics, version).ConfigureAwait(false); } /*-------------------------------------------------------------------------------------------------------------------------- @@ -332,7 +332,7 @@ public override sealed void Save([ValidatedNotNull] Topic topic, bool isRecurs /// Determines whether or not to recursively save . /// A list of s with unresolved topic references. /// The version to assign to the updates. - private void Save([NotNull]Topic topic, bool isRecursive, TopicCollection unresolvedTopics, DateTime version) { + private async Task Save([NotNull]Topic topic, bool isRecursive, TopicCollection unresolvedTopics, DateTime version) { /*-------------------------------------------------------------------------------------------------------------------------- | Validate parameters @@ -374,7 +374,7 @@ private void Save([NotNull]Topic topic, bool isRecursive, TopicCollection unreso /*-------------------------------------------------------------------------------------------------------------------------- | Execute core implementation \-------------------------------------------------------------------------------------------------------------------------*/ - SaveTopic(topic, version, !isRecursive || !unresolvedTopics.Contains(topic)); + await SaveTopic(topic, version, !isRecursive || !unresolvedTopics.Contains(topic)).ConfigureAwait(false); /*-------------------------------------------------------------------------------------------------------------------------- | Mark as clean @@ -399,10 +399,10 @@ private void Save([NotNull]Topic topic, bool isRecursive, TopicCollection unreso if (topic.Parent is not null && !topic.IsNew && topic.IsDirty("Parent")) { var topicIndex = topic.Parent.Children.IndexOf(topic); if (topicIndex > 0) { - Move(topic, topic.Parent, topic.Parent.Children[topicIndex - 1]); + await Move(topic, topic.Parent, topic.Parent.Children[topicIndex - 1]).ConfigureAwait(false); } else { - Move(topic, topic.Parent); + await Move(topic, topic.Parent).ConfigureAwait(false); } } @@ -454,7 +454,7 @@ _contentTypeDescriptors is not null && \-------------------------------------------------------------------------------------------------------------------------*/ if (isRecursive && topic.IsLoaded(TopicPayload.Children)) { foreach (var childTopic in topic.Children.ToList()) { - Save(childTopic, isRecursive, unresolvedTopics, version); + await Save(childTopic, isRecursive, unresolvedTopics, version).ConfigureAwait(false); } } @@ -485,13 +485,13 @@ _contentTypeDescriptors is not null && /// call isRecursive; in that case, will circle back and attempt to save them /// after the rest of the topic graph has been saved. /// - protected abstract void SaveTopic([NotNull] Topic topic, DateTime version, bool persistRelationships); + protected abstract Task SaveTopic([NotNull] Topic topic, DateTime version, bool persistRelationships); /*============================================================================================================================ | METHOD: MOVE \---------------------------------------------------------------------------------------------------------------------------*/ /// - public override sealed void Move([ValidatedNotNull]Topic topic, [ValidatedNotNull]Topic target, Topic? sibling = null) { + public override sealed async Task Move([ValidatedNotNull]Topic topic, [ValidatedNotNull]Topic target, Topic? sibling = null) { /*-------------------------------------------------------------------------------------------------------------------------- | Validate parameters @@ -518,7 +518,7 @@ topic.Parent is not null && | Execute core implementation \-------------------------------------------------------------------------------------------------------------------------*/ if (!topic.IsNew && !target.IsNew && !(sibling?.IsNew?? true)) { - MoveTopic(topic, target, sibling); + await MoveTopic(topic, target, sibling).ConfigureAwait(false); } /*-------------------------------------------------------------------------------------------------------------------------- @@ -572,13 +572,13 @@ topic.Parent is not null && /// The derived implementation of is then left to focus exclusively on the /// core logic of persisting the change to the underlying data store. /// - protected abstract void MoveTopic(Topic topic, Topic target, Topic? sibling = null); + protected abstract Task MoveTopic(Topic topic, Topic target, Topic? sibling = null); /*============================================================================================================================ | METHOD: DELETE \---------------------------------------------------------------------------------------------------------------------------*/ /// - public override sealed void Delete([ValidatedNotNull]Topic topic, bool isRecursive = false) { + public override sealed async Task Delete([ValidatedNotNull]Topic topic, bool isRecursive = false) { /*-------------------------------------------------------------------------------------------------------------------------- | Validate parameters @@ -614,7 +614,7 @@ public override sealed void Delete([ValidatedNotNull]Topic topic, bool isRecur | Execute core implementation \-------------------------------------------------------------------------------------------------------------------------*/ if (!topic.IsNew) { - DeleteTopic(topic); + await DeleteTopic(topic).ConfigureAwait(false); } /*-------------------------------------------------------------------------------------------------------------------------- @@ -700,7 +700,7 @@ public override sealed void Delete([ValidatedNotNull]Topic topic, bool isRecur /// derived implementation of is then left to focus exclusively on the core logic of /// persisting the change to the underlying data store. /// - protected abstract void DeleteTopic(Topic topic); + protected abstract Task DeleteTopic(Topic topic); /*============================================================================================================================ | METHOD: GET ATTRIBUTES diff --git a/OnTopic/Repositories/TopicRepositoryDecorator.cs b/OnTopic/Repositories/TopicRepositoryDecorator.cs index 1363ca7c..5202c226 100644 --- a/OnTopic/Repositories/TopicRepositoryDecorator.cs +++ b/OnTopic/Repositories/TopicRepositoryDecorator.cs @@ -109,20 +109,20 @@ protected TopicRepositoryDecorator(ITopicRepository topicRepository) : base() { | METHOD: REFRESH \---------------------------------------------------------------------------------------------------------------------------*/ /// - public override void Refresh(Topic referenceTopic, DateTime since) => TopicRepository.Refresh(referenceTopic, since); + public override Task Refresh(Topic referenceTopic, DateTime since) => TopicRepository.Refresh(referenceTopic, since); /*============================================================================================================================ | METHOD: ROLLBACK \---------------------------------------------------------------------------------------------------------------------------*/ /// - public override void Rollback(Topic topic, DateTime version) => TopicRepository.Rollback(topic, version); + public override Task Rollback(Topic topic, DateTime version) => TopicRepository.Rollback(topic, version); /*============================================================================================================================ | METHOD: SAVE \---------------------------------------------------------------------------------------------------------------------------*/ /// - public override void Save(Topic topic, bool isRecursive = false) { - TopicRepository.Save(topic, isRecursive); + public override async Task Save(Topic topic, bool isRecursive = false) { + await TopicRepository.Save(topic, isRecursive).ConfigureAwait(false); StampResolver(topic); } @@ -130,12 +130,12 @@ public override void Save(Topic topic, bool isRecursive = false) { | METHOD: MOVE \---------------------------------------------------------------------------------------------------------------------------*/ /// - public override void Move(Topic topic, Topic target, Topic? sibling = null) => TopicRepository.Move(topic, target, sibling); + public override Task Move(Topic topic, Topic target, Topic? sibling = null) => TopicRepository.Move(topic, target, sibling); /*============================================================================================================================ | METHOD: DELETE \---------------------------------------------------------------------------------------------------------------------------*/ /// - public override void Delete(Topic topic, bool isRecursive = false) => TopicRepository.Delete(topic, isRecursive); + public override Task Delete(Topic topic, bool isRecursive = false) => TopicRepository.Delete(topic, isRecursive); } //Class \ No newline at end of file From eb5c6a309a74dbe60de7f164500f833cdc0d3ddd Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Wed, 8 Jul 2026 17:08:37 -0700 Subject: [PATCH 114/337] Move xunit to async tests This is not only possible, but encouraged with xunit 3, which we recently upgraded to. Further, it helps us utilize the newly introduced async `ITopicRepository` implementations (a3b73602, caab55a2). --- .../TopicRepositoryExtensionsTest.cs | 8 +- .../HierarchicalTopicMappingServiceTest.cs | 8 +- OnTopic.Tests/ITopicRepositoryTest.cs | 44 +++--- .../ReverseTopicMappingServiceTest.cs | 6 +- OnTopic.Tests/SqlTopicRepositoryTest.cs | 96 ++++++------- OnTopic.Tests/TopicMappingServiceTest.cs | 10 +- OnTopic.Tests/TopicQueryingTest.cs | 8 +- OnTopic.Tests/TopicRepositoryBaseTest.cs | 130 +++++++++--------- 8 files changed, 155 insertions(+), 155 deletions(-) diff --git a/OnTopic.AspNetCore.Mvc.Tests/TopicRepositoryExtensionsTest.cs b/OnTopic.AspNetCore.Mvc.Tests/TopicRepositoryExtensionsTest.cs index 22ad2e47..74109b0c 100644 --- a/OnTopic.AspNetCore.Mvc.Tests/TopicRepositoryExtensionsTest.cs +++ b/OnTopic.AspNetCore.Mvc.Tests/TopicRepositoryExtensionsTest.cs @@ -48,10 +48,10 @@ public TopicRepositoryExtensionsTest(StubTopicRepository topicRepository) { /// Establishes route data and ensures that a topic is correctly identified based on that route. /// [Fact] - public void Load_ByRoute_ReturnsTopic() { + public async Task Load_ByRoute_ReturnsTopic() { var routes = new RouteData(); - var topic = _topicRepository.Load("Root:Web:Web_0:Web_0_1:Web_0_1_1").GetAwaiter().GetResult(); + var topic = await _topicRepository.Load("Root:Web:Web_0:Web_0_1:Web_0_1_1"); routes.Values.Add("rootTopic", "Web"); routes.Values.Add("path", "Web_0/Web_0_1/Web_0_1_1"); @@ -71,10 +71,10 @@ public void Load_ByRoute_ReturnsTopic() { /// Establishes route data and ensures that the root topic is correctly identified based on that route. /// [Fact] - public void Load_ByRoute_ReturnsRootTopic() { + public async Task Load_ByRoute_ReturnsRootTopic() { var routes = new RouteData(); - var topic = _topicRepository.Load("Root").GetAwaiter().GetResult(); + var topic = await _topicRepository.Load("Root"); routes.Values.Add("path", "Root/"); diff --git a/OnTopic.Tests/HierarchicalTopicMappingServiceTest.cs b/OnTopic.Tests/HierarchicalTopicMappingServiceTest.cs index 07f2a28d..14b67f26 100644 --- a/OnTopic.Tests/HierarchicalTopicMappingServiceTest.cs +++ b/OnTopic.Tests/HierarchicalTopicMappingServiceTest.cs @@ -141,7 +141,7 @@ public void GetHierarchicalRoot_WithDeepTopic_ReturnsRoot() { [Fact] public async Task GetViewModel_WithTwoLevels_ReturnsGraph() { - var rootTopic = _topicRepository.Load("Root:Web").GetAwaiter().GetResult(); + var rootTopic = await _topicRepository.Load("Root:Web"); var viewModel = await _hierarchicalMappingService.GetViewModelAsync(rootTopic, 1); Assert.NotNull(viewModel); @@ -160,7 +160,7 @@ public async Task GetViewModel_WithTwoLevels_ReturnsGraph() { [Fact] public async Task GetViewModel_WithValidationDelegate_ExcludesTopics() { - var rootTopic = _topicRepository.Load("Root:Web").GetAwaiter().GetResult(); + var rootTopic = await _topicRepository.Load("Root:Web"); var viewModel = await _hierarchicalMappingService .GetViewModelAsync(rootTopic, 2, (t) => t.Key.EndsWith('1')); @@ -180,8 +180,8 @@ public async Task GetViewModel_WithValidationDelegate_ExcludesTopics() { [Fact] public async Task GetViewModel_WithDisabled_ExcludesDisabled() { - var rootTopic = _topicRepository.Load("Root:Web:Web_3").GetAwaiter().GetResult()!; - var disabledTopic = _topicRepository.Load("Root:Web:Web_3:Web_3_0").GetAwaiter().GetResult(); + var rootTopic = (await _topicRepository.Load("Root:Web:Web_3"))!; + var disabledTopic = await _topicRepository.Load("Root:Web:Web_3:Web_3_0"); Contract.Assume(disabledTopic); diff --git a/OnTopic.Tests/ITopicRepositoryTest.cs b/OnTopic.Tests/ITopicRepositoryTest.cs index 6bd0fa46..f807c1bf 100644 --- a/OnTopic.Tests/ITopicRepositoryTest.cs +++ b/OnTopic.Tests/ITopicRepositoryTest.cs @@ -63,9 +63,9 @@ public ITopicRepositoryTest(TopicInfrastructureFixture fixt /// Loads the default topic and ensures there are the expected number of children. /// [Fact] - public void Load_Default_ReturnsTopicTopic() { + public async Task Load_Default_ReturnsTopicTopic() { - var rootTopic = _topicRepository.Load().GetAwaiter().GetResult(); + var rootTopic = await _topicRepository.Load(); Assert.Equal(2, rootTopic?.Children.Count); Assert.Equal("Configuration", rootTopic?.Children.First().Key); @@ -80,8 +80,8 @@ public void Load_Default_ReturnsTopicTopic() { /// Loads topics and ensures there are the expected number of children. /// [Fact] - public void Load_ValidUniqueKey_ReturnsCorrectTopic() => - Assert.Equal("Page", _topicRepository.Load("Root:Configuration:ContentTypes:Page").GetAwaiter().GetResult()?.Key); + public async Task Load_ValidUniqueKey_ReturnsCorrectTopic() => + Assert.Equal("Page", (await _topicRepository.Load("Root:Configuration:ContentTypes:Page"))?.Key); /*============================================================================================================================ | TEST: LOAD: INVALID UNIQUE KEY: RETURNS NULL @@ -90,8 +90,8 @@ public void Load_ValidUniqueKey_ReturnsCorrectTopic() => /// Loads invalid topic key and ensures a null is returned. /// [Fact] - public void Load_InvalidUniqueKey_ReturnsTopic() => - Assert.Null(_topicRepository.Load("Root:Configuration:ContentTypes:InvalidContentType").GetAwaiter().GetResult()); + public async Task Load_InvalidUniqueKey_ReturnsTopic() => + Assert.Null(await _topicRepository.Load("Root:Configuration:ContentTypes:InvalidContentType")); /*============================================================================================================================ | TEST: LOAD: VALID TOPIC ID: RETURNS CORRECT TOPIC @@ -100,9 +100,9 @@ public void Load_InvalidUniqueKey_ReturnsTopic() => /// Loads topic by ID and ensures it is found. /// [Fact] - public void Load_ValidTopicId_ReturnsCorrectTopic() { + public async Task Load_ValidTopicId_ReturnsCorrectTopic() { - var topic = _topicRepository.Load(11111).GetAwaiter().GetResult(); + var topic = await _topicRepository.Load(11111); Assert.NotNull(topic); Assert.Equal("Web_1_1_1_1", topic?.Key); @@ -116,8 +116,8 @@ public void Load_ValidTopicId_ReturnsCorrectTopic() { /// Loads topic by an incorrect ID and ensures it a null is returned. /// [Fact] - public void Load_InvalidTopicId_ReturnsNull() => - Assert.Null(_topicRepository.Load(9999999).GetAwaiter().GetResult()); + public async Task Load_InvalidTopicId_ReturnsNull() => + Assert.Null(await _topicRepository.Load(9999999)); /*============================================================================================================================ | TEST: SAVE @@ -126,17 +126,17 @@ public void Load_InvalidTopicId_ReturnsNull() => /// Saves topics and ensures their identifiers are properly set. /// [Fact] - public void Save() { + public async Task Save() { var topic = new Topic("Test", "Page"); var child = new Topic("Child", "Page", topic); - _topicRepository.Save(topic); + await _topicRepository.Save(topic); Assert.NotEqual(-1, topic.Id); Assert.Equal(-1, child.Id); - _topicRepository.Save(topic, true); + await _topicRepository.Save(topic, true); Assert.NotEqual(-1, child.Id); @@ -149,14 +149,14 @@ public void Save() { /// Moves topics and ensures their parents are correctly set. /// [Fact] - public void Move_ToNewParent_ConfirmedMove() { + public async Task Move_ToNewParent_ConfirmedMove() { var source = new Topic("OriginalParent", "Page"); var destination = new Topic("NewParent", "Page"); var topic = new Topic("Topic", "Page", source); _ = new Topic("Sibling", "Page", source); - _topicRepository.Move(topic, destination); + await _topicRepository.Move(topic, destination); Assert.Equal(topic.Parent, destination); Assert.Single(source.Children); @@ -171,13 +171,13 @@ public void Move_ToNewParent_ConfirmedMove() { /// Moves topic next to a different sibling and ensures it ends up in the correct location. /// [Fact] - public void Move_ToNewSibling_ConfirmedMove() { + public async Task Move_ToNewSibling_ConfirmedMove() { var parent = new Topic("OriginalParent", "Page"); var topic = new Topic("Topic", "Page", parent); var sibling = new Topic("Sibling", "Page", parent); - _topicRepository.Move(topic, parent, sibling); + await _topicRepository.Move(topic, parent, sibling); Assert.Equal(topic.Parent, parent); Assert.Equal(2, parent.Children.Count); @@ -193,13 +193,13 @@ public void Move_ToNewSibling_ConfirmedMove() { /// Deletes a topic to ensure it is properly removed. /// [Fact] - public void Delete_Topic_Removed() { + public async Task Delete_Topic_Removed() { var parent = new Topic("OriginalParent", "Page"); var topic = new Topic("Topic", "Page", parent); _ = new Topic("child", "Page", topic); - _topicRepository.Delete(topic, true); + await _topicRepository.Delete(topic, true); Assert.Empty(parent.Children); @@ -214,14 +214,14 @@ public void Delete_Topic_Removed() { /// and not the immediate . /// [Fact] - public void Delete_DeleteEvent_IsFired() { + public async Task Delete_DeleteEvent_IsFired() { var topic = new Topic("Test", "Page"); var hasFired = false; - _topicRepository.Save(topic); + await _topicRepository.Save(topic); _topicRepository.TopicDeleted += eventHandler; - _topicRepository.Delete(topic); + await _topicRepository.Delete(topic); Assert.True(hasFired); diff --git a/OnTopic.Tests/ReverseTopicMappingServiceTest.cs b/OnTopic.Tests/ReverseTopicMappingServiceTest.cs index 2b6cced8..8252d991 100644 --- a/OnTopic.Tests/ReverseTopicMappingServiceTest.cs +++ b/OnTopic.Tests/ReverseTopicMappingServiceTest.cs @@ -334,7 +334,7 @@ public async Task Map_NestedTopics_ReturnsMappedTopic() { [Fact] public async Task Map_TopicReferences_ReturnsMappedTopic() { - var topic = _topicRepository.Load("Root:Configuration:ContentTypes:Attributes:Title").GetAwaiter().GetResult(); + var topic = await _topicRepository.Load("Root:Configuration:ContentTypes:Attributes:Title"); Contract.Assume(topic); @@ -362,8 +362,8 @@ public async Task Map_TopicReferences_ReturnsMappedTopic() { [Fact] public async Task Map_NullTopicReference_Delete() { - var topic = _topicRepository.Load("Root:Configuration:ContentTypes:Attributes:Title").GetAwaiter().GetResult(); - var baseTopic = _topicRepository.Load("Root:Configuration:ContentTypes:Attributes:Key").GetAwaiter().GetResult(); + var topic = await _topicRepository.Load("Root:Configuration:ContentTypes:Attributes:Title"); + var baseTopic = await _topicRepository.Load("Root:Configuration:ContentTypes:Attributes:Key"); Contract.Assume(topic); diff --git a/OnTopic.Tests/SqlTopicRepositoryTest.cs b/OnTopic.Tests/SqlTopicRepositoryTest.cs index eeac8299..b1cffd01 100644 --- a/OnTopic.Tests/SqlTopicRepositoryTest.cs +++ b/OnTopic.Tests/SqlTopicRepositoryTest.cs @@ -33,7 +33,7 @@ public class SqlTopicRepositoryTest { /// a topic with those values is returned. /// [Fact] - public void LoadTopicGraph_WithTopic_ReturnsTopic() { + public async Task LoadTopicGraph_WithTopic_ReturnsTopic() { using var topics = new TopicsDataTable(); @@ -41,7 +41,7 @@ public void LoadTopicGraph_WithTopic_ReturnsTopic() { using var tableReader = new DataTableReader(topics); - var topic = tableReader.LoadTopicGraphAsync().GetAwaiter().GetResult(); + var topic = await tableReader.LoadTopicGraphAsync(); Assert.NotNull(topic); Assert.Equal(1, topic.Id); @@ -56,7 +56,7 @@ public void LoadTopicGraph_WithTopic_ReturnsTopic() { /// different parent than the existing referenceTopic and confirms that the topic's parent is updated. /// [Fact] - public void LoadTopicGraph_WithNewParent_UpdatesParent() { + public async Task LoadTopicGraph_WithNewParent_UpdatesParent() { using var topics = new TopicsDataTable(); @@ -69,7 +69,7 @@ public void LoadTopicGraph_WithNewParent_UpdatesParent() { using var tableReader = new DataTableReader(topics); - tableReader.LoadTopicGraphAsync(referenceTopic: topic).GetAwaiter().GetResult(); + await tableReader.LoadTopicGraphAsync(referenceTopic: topic); Assert.Equal(parent2, child.Parent); @@ -83,7 +83,7 @@ public void LoadTopicGraph_WithNewParent_UpdatesParent() { /// that a topic with those values is returned. /// [Fact] - public void LoadTopicGraph_WithAttributes_ReturnsAttributes() { + public async Task LoadTopicGraph_WithAttributes_ReturnsAttributes() { using var topics = new TopicsDataTable(); using var attributes = new AttributesDataTable(); @@ -93,7 +93,7 @@ public void LoadTopicGraph_WithAttributes_ReturnsAttributes() { using var tableReader = new DataTableReader([topics, attributes]); - var topic = tableReader.LoadTopicGraphAsync().GetAwaiter().GetResult(); + var topic = await tableReader.LoadTopicGraphAsync(); Assert.NotNull(topic); Assert.Equal(1, topic.Id); @@ -109,7 +109,7 @@ public void LoadTopicGraph_WithAttributes_ReturnsAttributes() { /// a deleted attribute and confirms that an existing reference topic with that attribute has the value removed. /// [Fact] - public void LoadTopicGraph_WithNullAttributes_RemovesAttribute() { + public async Task LoadTopicGraph_WithNullAttributes_RemovesAttribute() { using var topics = new TopicsDataTable(); using var attributes = new AttributesDataTable(); @@ -123,7 +123,7 @@ public void LoadTopicGraph_WithNullAttributes_RemovesAttribute() { using var tableReader = new DataTableReader([topics, attributes]); - tableReader.LoadTopicGraphAsync(referenceTopic: topic).GetAwaiter().GetResult(); + await tableReader.LoadTopicGraphAsync(referenceTopic: topic); Assert.Null(topic.Attributes.GetValue("Test")); @@ -137,7 +137,7 @@ public void LoadTopicGraph_WithNullAttributes_RemovesAttribute() { /// confirms that a topic with those values is returned. /// [Fact] - public void LoadTopicGraph_WithRelationship_ReturnsRelationship() { + public async Task LoadTopicGraph_WithRelationship_ReturnsRelationship() { using var topics = new TopicsDataTable(); using var empty = new AttributesDataTable(); @@ -149,7 +149,7 @@ public void LoadTopicGraph_WithRelationship_ReturnsRelationship() { using var tableReader = new DataTableReader([topics, empty, empty, relationships]); - var topic = tableReader.LoadTopicGraphAsync().GetAwaiter().GetResult(); + var topic = await tableReader.LoadTopicGraphAsync(); Assert.NotNull(topic); Assert.Equal(1, topic.Id); @@ -166,7 +166,7 @@ public void LoadTopicGraph_WithRelationship_ReturnsRelationship() { /// missing and confirms that returns . /// [Fact] - public void LoadTopicGraph_WithMissingRelationship_NotFullyLoaded() { + public async Task LoadTopicGraph_WithMissingRelationship_NotFullyLoaded() { using var topics = new TopicsDataTable(); using var empty = new AttributesDataTable(); @@ -177,7 +177,7 @@ public void LoadTopicGraph_WithMissingRelationship_NotFullyLoaded() { using var tableReader = new DataTableReader([topics, empty, empty, relationships]); - var topic = tableReader.LoadTopicGraphAsync().GetAwaiter().GetResult(); + var topic = await tableReader.LoadTopicGraphAsync(); Assert.NotNull(topic); Assert.Equal(1, topic.Id); @@ -194,7 +194,7 @@ public void LoadTopicGraph_WithMissingRelationship_NotFullyLoaded() { /// confirms that a topic with those values is returned. /// [Fact] - public void LoadTopicGraph_WithReference_ReturnsReference() { + public async Task LoadTopicGraph_WithReference_ReturnsReference() { using var topics = new TopicsDataTable(); using var empty = new AttributesDataTable(); @@ -206,7 +206,7 @@ public void LoadTopicGraph_WithReference_ReturnsReference() { using var tableReader = new DataTableReader([topics, empty, empty, empty, references]); - var topic = tableReader.LoadTopicGraphAsync().GetAwaiter().GetResult(); + var topic = await tableReader.LoadTopicGraphAsync(); Assert.NotNull(topic); Assert.Equal(1, topic.Id); @@ -223,7 +223,7 @@ public void LoadTopicGraph_WithReference_ReturnsReference() { /// confirms that a topic with those values is returned. /// [Fact] - public void LoadTopicGraph_WithExternalReference_ReturnsReference() { + public async Task LoadTopicGraph_WithExternalReference_ReturnsReference() { using var topics = new TopicsDataTable(); using var empty = new AttributesDataTable(); @@ -236,7 +236,7 @@ public void LoadTopicGraph_WithExternalReference_ReturnsReference() { using var tableReader = new DataTableReader([topics, empty, empty, empty, references]); - var topic = tableReader.LoadTopicGraphAsync(1, referenceTopic, false).GetAwaiter().GetResult(); + var topic = await tableReader.LoadTopicGraphAsync(1, referenceTopic, false); Assert.NotNull(topic); Assert.Equal(1, topic.Id); @@ -255,7 +255,7 @@ public void LoadTopicGraph_WithExternalReference_ReturnsReference() { /// "TopicReferencesDataTable"/>. /// [Fact] - public void LoadTopicGraph_WithDeletedReference_RemovesExistingReference() { + public async Task LoadTopicGraph_WithDeletedReference_RemovesExistingReference() { using var topics = new TopicsDataTable(); using var empty = new AttributesDataTable(); @@ -270,7 +270,7 @@ public void LoadTopicGraph_WithDeletedReference_RemovesExistingReference() { using var tableReader = new DataTableReader([topics, empty, empty, empty, references]); - tableReader.LoadTopicGraphAsync(1, referenceTopic, false).GetAwaiter().GetResult(); + await tableReader.LoadTopicGraphAsync(1, referenceTopic, false); Assert.Null(referenceTopic.References.GetValue("Reference")); Assert.Equal(LoadState.Loaded, referenceTopic.References.LoadState); @@ -285,7 +285,7 @@ public void LoadTopicGraph_WithDeletedReference_RemovesExistingReference() { /// missing and confirms that returns . /// [Fact] - public void LoadTopicGraph_WithMissingReference_NotFullyLoaded() { + public async Task LoadTopicGraph_WithMissingReference_NotFullyLoaded() { using var topics = new TopicsDataTable(); using var empty = new AttributesDataTable(); @@ -296,7 +296,7 @@ public void LoadTopicGraph_WithMissingReference_NotFullyLoaded() { using var tableReader = new DataTableReader([topics, empty, empty, empty, references]); - var topic = tableReader.LoadTopicGraphAsync().GetAwaiter().GetResult(); + var topic = await tableReader.LoadTopicGraphAsync(); Assert.NotNull(topic); Assert.Equal(1, topic.Id); @@ -313,7 +313,7 @@ public void LoadTopicGraph_WithMissingReference_NotFullyLoaded() { /// and confirms that it is deleted from the referenceTopic graph. /// [Fact] - public void LoadTopicGraph_WithDeletedRelationship_RemovesRelationship() { + public async Task LoadTopicGraph_WithDeletedRelationship_RemovesRelationship() { var topic = new Topic("Test", "Container", null, 1); var child = new Topic("Child", "Container", topic, 2); @@ -328,7 +328,7 @@ public void LoadTopicGraph_WithDeletedRelationship_RemovesRelationship() { using var tableReader = new DataTableReader([empty, empty, empty, relationships]); - tableReader.LoadTopicGraphAsync(referenceTopic: related).GetAwaiter().GetResult(); + await tableReader.LoadTopicGraphAsync(referenceTopic: related); Assert.Empty(topic.Relationships.GetValues("Test")); @@ -347,7 +347,7 @@ public void LoadTopicGraph_WithDeletedRelationship_RemovesRelationship() { /// when extended attributes are deferred. /// [Fact] - public void LoadTopicGraph_IndexedOnlyWithRelationship_ReturnsLoaded() { + public async Task LoadTopicGraph_IndexedOnlyWithRelationship_ReturnsLoaded() { using var topics = new TopicsDataTable(); using var empty = new AttributesDataTable(); @@ -359,7 +359,7 @@ public void LoadTopicGraph_IndexedOnlyWithRelationship_ReturnsLoaded() { using var tableReader = new DataTableReader([topics, empty, empty, relationships]); - var topic = tableReader.LoadTopicGraphAsync().GetAwaiter().GetResult(); + var topic = await tableReader.LoadTopicGraphAsync(); Assert.NotNull(topic); Assert.True(topic.IsLoaded(TopicPayload.Relationships)); @@ -379,7 +379,7 @@ public void LoadTopicGraph_IndexedOnlyWithRelationship_ReturnsLoaded() { /// resolver calls EnsureLoaded(Relationships) for the topic. /// [Fact] - public void LoadTopicGraph_IndexedOnlyWithMissingRelationship_ReturnsNotLoaded() { + public async Task LoadTopicGraph_IndexedOnlyWithMissingRelationship_ReturnsNotLoaded() { using var topics = new TopicsDataTable(); using var empty = new AttributesDataTable(); @@ -390,7 +390,7 @@ public void LoadTopicGraph_IndexedOnlyWithMissingRelationship_ReturnsNotLoaded() using var tableReader = new DataTableReader([topics, empty, empty, relationships]); - var topic = tableReader.LoadTopicGraphAsync().GetAwaiter().GetResult(); + var topic = await tableReader.LoadTopicGraphAsync(); Assert.NotNull(topic); Assert.False(topic.IsLoaded(TopicPayload.Relationships)); @@ -405,7 +405,7 @@ public void LoadTopicGraph_IndexedOnlyWithMissingRelationship_ReturnsNotLoaded() /// resident, and confirms that returns . /// [Fact] - public void LoadTopicGraph_IndexedOnlyWithReference_ReturnsLoaded() { + public async Task LoadTopicGraph_IndexedOnlyWithReference_ReturnsLoaded() { using var topics = new TopicsDataTable(); using var empty = new AttributesDataTable(); @@ -417,7 +417,7 @@ public void LoadTopicGraph_IndexedOnlyWithReference_ReturnsLoaded() { using var tableReader = new DataTableReader([topics, empty, empty, empty, references]); - var topic = tableReader.LoadTopicGraphAsync().GetAwaiter().GetResult(); + var topic = await tableReader.LoadTopicGraphAsync(); Assert.NotNull(topic); Assert.True(topic.IsLoaded(TopicPayload.References)); @@ -433,7 +433,7 @@ public void LoadTopicGraph_IndexedOnlyWithReference_ReturnsLoaded() { /// "LoadState.NotLoaded"/>. /// [Fact] - public void LoadTopicGraph_IndexedOnlyWithMissingReference_ReturnsNotLoaded() { + public async Task LoadTopicGraph_IndexedOnlyWithMissingReference_ReturnsNotLoaded() { using var topics = new TopicsDataTable(); using var empty = new AttributesDataTable(); @@ -444,7 +444,7 @@ public void LoadTopicGraph_IndexedOnlyWithMissingReference_ReturnsNotLoaded() { using var tableReader = new DataTableReader([topics, empty, empty, empty, references]); - var topic = tableReader.LoadTopicGraphAsync().GetAwaiter().GetResult(); + var topic = await tableReader.LoadTopicGraphAsync(); Assert.NotNull(topic); Assert.False(topic.IsLoaded(TopicPayload.References)); @@ -460,7 +460,7 @@ public void LoadTopicGraph_IndexedOnlyWithMissingReference_ReturnsNotLoaded() { /// block DeleteUnmatched on save until the edge is resolved via EnsureLoaded. /// [Fact] - public void LoadTopicGraph_WithMissingRelationship_SetsNotLoaded() { + public async Task LoadTopicGraph_WithMissingRelationship_SetsNotLoaded() { using var topics = new TopicsDataTable(); using var empty = new AttributesDataTable(); @@ -471,7 +471,7 @@ public void LoadTopicGraph_WithMissingRelationship_SetsNotLoaded() { using var tableReader = new DataTableReader([topics, empty, empty, relationships]); - var topic = tableReader.LoadTopicGraphAsync().GetAwaiter().GetResult(); + var topic = await tableReader.LoadTopicGraphAsync(); Assert.NotNull(topic); Assert.False(topic.IsLoaded(TopicPayload.Relationships)); @@ -487,7 +487,7 @@ public void LoadTopicGraph_WithMissingRelationship_SetsNotLoaded() { /// DeleteUnmatched on save until the reference is resolved via EnsureLoaded. /// [Fact] - public void LoadTopicGraph_WithMissingReference_SetsNotLoaded() { + public async Task LoadTopicGraph_WithMissingReference_SetsNotLoaded() { using var topics = new TopicsDataTable(); using var empty = new AttributesDataTable(); @@ -498,7 +498,7 @@ public void LoadTopicGraph_WithMissingReference_SetsNotLoaded() { using var tableReader = new DataTableReader([topics, empty, empty, empty, references]); - var topic = tableReader.LoadTopicGraphAsync().GetAwaiter().GetResult(); + var topic = await tableReader.LoadTopicGraphAsync(); Assert.NotNull(topic); Assert.False(topic.IsLoaded(TopicPayload.References)); @@ -513,7 +513,7 @@ public void LoadTopicGraph_WithMissingReference_SetsNotLoaded() { /// confirms that a topic with those values is returned. /// [Fact] - public void LoadTopicGraph_WithVersionHistory_ReturnsVersions() { + public async Task LoadTopicGraph_WithVersionHistory_ReturnsVersions() { using var topics = new TopicsDataTable(); using var empty = new AttributesDataTable(); @@ -524,7 +524,7 @@ public void LoadTopicGraph_WithVersionHistory_ReturnsVersions() { using var tableReader = new DataTableReader([topics, empty, empty, empty, empty, versions]); - var topic = tableReader.LoadTopicGraphAsync().GetAwaiter().GetResult(); + var topic = await tableReader.LoadTopicGraphAsync(); Assert.NotNull(topic); Assert.Equal(1, topic.Id); @@ -542,7 +542,7 @@ public void LoadTopicGraph_WithVersionHistory_ReturnsVersions() { /// . /// [Fact] - public void LoadTopicGraph_WithExtendedDeferredAndBlob_ReturnsNotLoaded() { + public async Task LoadTopicGraph_WithExtendedDeferredAndBlob_ReturnsNotLoaded() { using var topics = new TopicsDataTable(); @@ -550,7 +550,7 @@ public void LoadTopicGraph_WithExtendedDeferredAndBlob_ReturnsNotLoaded() { using var tableReader = new DataTableReader(topics); - var topic = tableReader.LoadTopicGraphAsync().GetAwaiter().GetResult(); + var topic = await tableReader.LoadTopicGraphAsync(); Assert.NotNull(topic); Assert.False(topic.IsLoaded(TopicPayload.ExtendedAttributes)); @@ -566,7 +566,7 @@ public void LoadTopicGraph_WithExtendedDeferredAndBlob_ReturnsNotLoaded() { /// boundary is , thus avoiding a wasted round-trip. /// [Fact] - public void LoadTopicGraph_WithExtendedDeferredAndNoBlob_ReturnsLoaded() { + public async Task LoadTopicGraph_WithExtendedDeferredAndNoBlob_ReturnsLoaded() { using var topics = new TopicsDataTable(); @@ -574,7 +574,7 @@ public void LoadTopicGraph_WithExtendedDeferredAndNoBlob_ReturnsLoaded() { using var tableReader = new DataTableReader(topics); - var topic = tableReader.LoadTopicGraphAsync().GetAwaiter().GetResult(); + var topic = await tableReader.LoadTopicGraphAsync(); Assert.NotNull(topic); Assert.Equal(LoadState.Loaded, topic.Attributes.LoadState); @@ -590,7 +590,7 @@ public void LoadTopicGraph_WithExtendedDeferredAndNoBlob_ReturnsLoaded() { /// extended-attribute boundary is . /// [Fact] - public void LoadTopicGraph_WithExtendedIncludedAndBlob_ReturnsLoaded() { + public async Task LoadTopicGraph_WithExtendedIncludedAndBlob_ReturnsLoaded() { using var topics = new TopicsDataTable(); @@ -598,7 +598,7 @@ public void LoadTopicGraph_WithExtendedIncludedAndBlob_ReturnsLoaded() { using var tableReader = new DataTableReader(topics); - var topic = tableReader.LoadTopicGraphAsync().GetAwaiter().GetResult(); + var topic = await tableReader.LoadTopicGraphAsync(); Assert.NotNull(topic); Assert.Equal(LoadState.Loaded, topic.Attributes.LoadState); @@ -614,7 +614,7 @@ public void LoadTopicGraph_WithExtendedIncludedAndBlob_ReturnsLoaded() { /// topic is a leaf with nothing to lazy-load). /// [Fact] - public void LoadTopicGraph_WithHasChildrenFalse_ReturnsChildrenLoaded() { + public async Task LoadTopicGraph_WithHasChildrenFalse_ReturnsChildrenLoaded() { using var topics = new TopicsDataTable(); @@ -622,7 +622,7 @@ public void LoadTopicGraph_WithHasChildrenFalse_ReturnsChildrenLoaded() { using var tableReader = new DataTableReader(topics); - var topic = tableReader.LoadTopicGraphAsync(1).GetAwaiter().GetResult(); + var topic = await tableReader.LoadTopicGraphAsync(1); Assert.True(topic?.IsLoaded(TopicPayload.Children)); @@ -637,7 +637,7 @@ public void LoadTopicGraph_WithHasChildrenFalse_ReturnsChildrenLoaded() { /// "LoadState.Loaded"/> (i.e., the subtree was loaded in full). /// [Fact] - public void LoadTopicGraph_WithHasChildrenAndLoadedChildren_ReturnsChildrenLoaded() { + public async Task LoadTopicGraph_WithHasChildrenAndLoadedChildren_ReturnsChildrenLoaded() { using var topics = new TopicsDataTable(); @@ -646,7 +646,7 @@ public void LoadTopicGraph_WithHasChildrenAndLoadedChildren_ReturnsChildrenLoade using var tableReader = new DataTableReader(topics); - var topic = tableReader.LoadTopicGraphAsync(1).GetAwaiter().GetResult(); + var topic = await tableReader.LoadTopicGraphAsync(1); Assert.True(topic?.IsLoaded(TopicPayload.Children)); @@ -662,7 +662,7 @@ public void LoadTopicGraph_WithHasChildrenAndLoadedChildren_ReturnsChildrenLoade /// scenario addressed by the seedTopicId parameter; i.e., loading ascendants and descendants. /// [Fact] - public void LoadTopicGraph_WithHasChildrenOnAncestorAndLoadedSubtree_SetsLoadStateCorrectly() { + public async Task LoadTopicGraph_WithHasChildrenOnAncestorAndLoadedSubtree_SetsLoadStateCorrectly() { using var topics = new TopicsDataTable(); @@ -674,7 +674,7 @@ public void LoadTopicGraph_WithHasChildrenOnAncestorAndLoadedSubtree_SetsLoadSta // The seed topic is Child (2); Root (1) is on the ancestor chain and is NotLoaded. // The Child (seed) and Grandchild are in the fully loaded subtree and are Loaded. - var seedTopic = tableReader.LoadTopicGraphAsync(2).GetAwaiter().GetResult(); + var seedTopic = await tableReader.LoadTopicGraphAsync(2); var rootTopic = seedTopic?.Parent; Assert.Equal(LoadState.NotLoaded, rootTopic?.Children.LoadState); diff --git a/OnTopic.Tests/TopicMappingServiceTest.cs b/OnTopic.Tests/TopicMappingServiceTest.cs index 1642564b..c18b2a78 100644 --- a/OnTopic.Tests/TopicMappingServiceTest.cs +++ b/OnTopic.Tests/TopicMappingServiceTest.cs @@ -849,7 +849,7 @@ public async Task Map_AlternateRelationship_ReturnsCorrectRelationship() { [Fact] public async Task Map_CustomCollection_ReturnsCollection() { - var topic = (ContentTypeDescriptor?)_topicRepository.Load("Root:Configuration:ContentTypes:Page").GetAwaiter().GetResult(); + var topic = (ContentTypeDescriptor?)await _topicRepository.Load("Root:Configuration:ContentTypes:Page"); var target = await _mappingService.MapAsync(topic); Assert.NotNull(topic); @@ -995,7 +995,7 @@ public async Task Map_MapToParent_ReturnsMappedModel() { [Fact] public async Task Map_MapAs_ReturnsTopicReference() { - var topicReference = _topicRepository.Load(11111).GetAwaiter().GetResult(); + var topicReference = await _topicRepository.Load(11111); Contract.Assume(topicReference); @@ -1020,7 +1020,7 @@ public async Task Map_MapAs_ReturnsTopicReference() { [Fact] public async Task Map_MapAs_ReturnsRelationships() { - var relatedTopic = _topicRepository.Load(11111).GetAwaiter().GetResult(); + var relatedTopic = await _topicRepository.Load(11111); Contract.Assume(relatedTopic); @@ -1046,7 +1046,7 @@ public async Task Map_MapAs_ReturnsRelationships() { [Fact] public async Task Map_TopicReferencesAsAttribute_ReturnsMappedModel() { - var topicReference = _topicRepository.Load(11111).GetAwaiter().GetResult(); + var topicReference = await _topicRepository.Load(11111); Contract.Assume(topicReference); @@ -1070,7 +1070,7 @@ public async Task Map_TopicReferencesAsAttribute_ReturnsMappedModel() { [Fact] public async Task Map_TopicReferences_ReturnsMappedModel() { - var topicReference = _topicRepository.Load(11111).GetAwaiter().GetResult(); + var topicReference = await _topicRepository.Load(11111); var topic = new Topic("Test", "TopicReference"); diff --git a/OnTopic.Tests/TopicQueryingTest.cs b/OnTopic.Tests/TopicQueryingTest.cs index 16855742..da8d7bab 100644 --- a/OnTopic.Tests/TopicQueryingTest.cs +++ b/OnTopic.Tests/TopicQueryingTest.cs @@ -223,9 +223,9 @@ public void GetByUniqueKey_InvalidKey_ReturnsNull() { /// Given a deeply nested , returns the expected . /// [Fact] - public void GetContentType_ValidContentType_ReturnsContentType() { + public async Task GetContentType_ValidContentType_ReturnsContentType() { - var topic = _topicRepository.Load(11111).GetAwaiter().GetResult(); + var topic = await _topicRepository.Load(11111); var contentTypeDescriptor = topic?.GetContentTypeDescriptor(); Assert.NotNull(contentTypeDescriptor); @@ -243,7 +243,7 @@ public void GetContentType_ValidContentType_ReturnsContentType() { [Fact] public async Task GetContentType_InvalidContentType_ReturnsNull() { - var parentTopic = _topicRepository.Load(11111).GetAwaiter().GetResult(); + var parentTopic = await _topicRepository.Load(11111); var topic = new Topic("Test", "NonExistent", parentTopic); var contentTypeDescriptor = topic.GetContentTypeDescriptor(); @@ -268,7 +268,7 @@ public async Task GetContentType_InvalidContentType_ReturnsNull() { [Fact] public async Task GetContentType_InvalidType_ReturnsNull() { - var parentTopic = _topicRepository.Load(11111).GetAwaiter().GetResult(); + var parentTopic = await _topicRepository.Load(11111); var topic = new Topic("Test", "Title", parentTopic); var contentTypeDescriptor = topic.GetContentTypeDescriptor(); diff --git a/OnTopic.Tests/TopicRepositoryBaseTest.cs b/OnTopic.Tests/TopicRepositoryBaseTest.cs index 2dbe1fa9..0bbc93ea 100644 --- a/OnTopic.Tests/TopicRepositoryBaseTest.cs +++ b/OnTopic.Tests/TopicRepositoryBaseTest.cs @@ -56,9 +56,9 @@ public TopicRepositoryBaseTest() { /// and confirms that the expected topic is returned. /// [Fact] - public void Load_ValidTopicId_ReturnsExpectedTopic() { + public async Task Load_ValidTopicId_ReturnsExpectedTopic() { - var topic = _topicRepository.Load(11111).GetAwaiter().GetResult(); + var topic = await _topicRepository.Load(11111); Assert.Equal(11111, topic?.Id); @@ -72,8 +72,8 @@ public void Load_ValidTopicId_ReturnsExpectedTopic() { /// "Topic.Id"/> and confirms that no topic is returned. /// [Fact] - public void Load_InvalidTopicId_ReturnsExpectedTopic() => - Assert.Null(_topicRepository.Load(11113).GetAwaiter().GetResult()); + public async Task Load_InvalidTopicId_ReturnsExpectedTopic() => + Assert.Null(await _topicRepository.Load(11113)); /*============================================================================================================================ | TEST: LOAD: NEGATIVE TOPIC ID: RETURNS ROOT TOPIC @@ -83,8 +83,8 @@ public void Load_InvalidTopicId_ReturnsExpectedTopic() => /// "Topic.Id"/> and confirms that the root topic is returned. /// [Fact] - public void Load_NegativeTopicId_ReturnsRootTopic() => - Assert.Equal("Root", _cachedTopicRepository.Load(-2).GetAwaiter().GetResult()?.GetUniqueKey()); + public async Task Load_NegativeTopicId_ReturnsRootTopic() => + Assert.Equal("Root", (await _cachedTopicRepository.Load(-2))?.GetUniqueKey()); /*============================================================================================================================ | TEST: LOAD: NARROW PAYLOAD: RETURNS TOPIC @@ -95,9 +95,9 @@ public void Load_NegativeTopicId_ReturnsRootTopic() => /// regardless of this parameter; the test simply verifies the signature is accepted. /// [Fact] - public void Load_WithNarrowPayload_ReturnsTopic() { + public async Task Load_WithNarrowPayload_ReturnsTopic() { - var topic = _topicRepository.Load(11111, payload: TopicPayload.None).GetAwaiter().GetResult(); + var topic = await _topicRepository.Load(11111, payload: TopicPayload.None); Assert.NotNull(topic); @@ -112,9 +112,9 @@ public void Load_WithNarrowPayload_ReturnsTopic() { /// defer extended attributes; this simply confirms no regression for stub-backed tests. /// [Fact] - public void Load_WithNarrowPayload_ExtendedAttributesLoaded() { + public async Task Load_WithNarrowPayload_ExtendedAttributesLoaded() { - var topic = _topicRepository.Load(11111, payload: TopicPayload.None).GetAwaiter().GetResult(); + var topic = await _topicRepository.Load(11111, payload: TopicPayload.None); Assert.NotNull(topic); Assert.Equal(LoadState.Loaded, topic.Attributes.LoadState); @@ -129,10 +129,10 @@ public void Load_WithNarrowPayload_ExtendedAttributesLoaded() { /// with that date is returned. /// [Fact] - public void Load_ValidDate_ReturnsTopic() { + public async Task Load_ValidDate_ReturnsTopic() { var version = DateTime.UtcNow.AddDays(-1); - var topic = _cachedTopicRepository.Load(11111, version).GetAwaiter().GetResult(); + var topic = await _cachedTopicRepository.Load(11111, version); Assert.True(topic?.VersionHistory.Contains(version)); Assert.Equal(version.AddTicks(-(version.Ticks % TimeSpan.TicksPerSecond)), topic?.LastModified); @@ -150,7 +150,7 @@ public void Load_ValidDate_ReturnsTopic() { public async Task Rollback_Topic_UpdatesLastModified() { var version = DateTime.UtcNow.AddDays(-1); - var topic = _topicRepository.Load(11111).GetAwaiter().GetResult(); + var topic = await _topicRepository.Load(11111); if (topic is not null) { topic.VersionHistory.Add(version); @@ -658,9 +658,9 @@ public void GetContentTypeDescriptor_GetValidContentType_ReturnsContentType() { /// attempts to retrieve it from the 's graph. /// [Fact] - public void GetContentTypeDescriptor_GetNewContentType_ReturnsFromTopicGraph() { + public async Task GetContentTypeDescriptor_GetNewContentType_ReturnsFromTopicGraph() { - var rootTopic = _topicRepository.Load("Root").GetAwaiter().GetResult(); + var rootTopic = await _topicRepository.Load("Root"); var contentTypes = _topicRepository.GetContentTypeDescriptors(); var rootContentType = contentTypes.GetValue("ContentTypes"); var newContentType = new ContentTypeDescriptor("NewContentType", "ContentTypeDescriptor", rootContentType); @@ -685,7 +685,7 @@ public void GetContentTypeDescriptor_GetNewContentType_ReturnsFromTopicGraph() { public async Task GetContentTypeDescriptor_MissingRootContentType_ReturnsNull() { var topicRepository = new StubTopicRepository(); - var configuration = topicRepository.Load("Root:Configuration").GetAwaiter().GetResult(); + var configuration = await topicRepository.Load("Root:Configuration"); var topic = new Topic("Test", "Page"); await topicRepository.Delete(configuration!, true); @@ -772,7 +772,7 @@ public async Task Save_ContentTypeDescriptor_UpdatesPermittedContentTypes() { [Fact] public async Task Save_NewTopic_UpdatesVersionHistory() { - var parent = _topicRepository.Load("Root:Web:Web_3:Web_3_0").GetAwaiter().GetResult(); + var parent = await _topicRepository.Load("Root:Web:Web_3:Web_3_0"); var topic = new Topic("Test", "Page", parent); await _topicRepository.Save(topic); @@ -791,7 +791,7 @@ public async Task Save_NewTopic_UpdatesVersionHistory() { [Fact] public async Task Save_IsRecursive_SavesChild() { - var parent = _topicRepository.Load("Root:Web:Web_3:Web_3_0").GetAwaiter().GetResult(); + var parent = await _topicRepository.Load("Root:Web:Web_3:Web_3_0"); var topic = new Topic("Test", "Page", parent); var child = new Topic("Child", "Page", topic); @@ -812,7 +812,7 @@ public async Task Save_IsRecursive_SavesChild() { [Fact] public async Task Save_UnresolvedReference_Resolves() { - var parent = _topicRepository.Load("Root:Web:Web_3:Web_3_0").GetAwaiter().GetResult(); + var parent = await _topicRepository.Load("Root:Web:Web_3:Web_3_0"); var topic = new Topic("Test", "Page", parent); var reference = new Topic("Reference", "Page", topic); @@ -832,7 +832,7 @@ public async Task Save_UnresolvedReference_Resolves() { [Fact] public async Task Save_UnresolvedReference_ThrowsException() { - var parent = _topicRepository.Load("Root:Web:Web_3:Web_3_0").GetAwaiter().GetResult(); + var parent = await _topicRepository.Load("Root:Web:Web_3:Web_3_0"); var topic = new Topic("Test", "Page", parent); var reference = new Topic("Reference", "Page", parent); @@ -993,13 +993,13 @@ public async Task Delete_AttributeDescriptor_UpdatesContentTypeCache() { /// event is raised. /// [Fact] - public void Load_TopicLoadedEvent_IsRaised() { + public async Task Load_TopicLoadedEvent_IsRaised() { var hasFired = false; _cachedTopicRepository.TopicLoaded += eventHandler; - var topic = _topicRepository.Load("Root:Web").GetAwaiter().GetResult(); + var topic = await _topicRepository.Load("Root:Web"); _cachedTopicRepository.TopicLoaded -= eventHandler; @@ -1017,15 +1017,15 @@ public void Load_TopicLoadedEvent_IsRaised() { /// "ITopicRepository.TopicLoaded"/> event is raised. /// [Fact] - public void Load_TopicLoadedEvent_IsRaisedWithVersion() { + public async Task Load_TopicLoadedEvent_IsRaisedWithVersion() { var hasFired = false; - var topicId = _topicRepository.Load("Root:Web").GetAwaiter().GetResult()?.Id; + var topicId = (await _topicRepository.Load("Root:Web"))?.Id; var version = DateTime.UtcNow; _cachedTopicRepository.TopicLoaded += eventHandler; - var topic = _topicRepository.Load(topicId?? -1, version).GetAwaiter().GetResult(); + var topic = await _topicRepository.Load(topicId?? -1, version); _cachedTopicRepository.TopicLoaded -= eventHandler; @@ -1045,14 +1045,14 @@ public void Load_TopicLoadedEvent_IsRaisedWithVersion() { /// "ITopicRepository.TopicDeleted"/> event is raised. /// [Fact] - public void Delete_TopicDeletedEvent_IsRaised() { + public async Task Delete_TopicDeletedEvent_IsRaised() { var topic = new Topic("Test", "Page"); var hasFired = false; - _cachedTopicRepository.Save(topic); + await _cachedTopicRepository.Save(topic); _cachedTopicRepository.TopicDeleted += eventHandler; - _cachedTopicRepository.Delete(topic); + await _cachedTopicRepository.Delete(topic); _cachedTopicRepository.TopicDeleted -= eventHandler; Assert.True(hasFired); @@ -1069,13 +1069,13 @@ public void Delete_TopicDeletedEvent_IsRaised() { /// /> event is raised. /// [Fact] - public void Save_TopicSavedEvent_IsRaised() { + public async Task Save_TopicSavedEvent_IsRaised() { var topic = new Topic("Test", "Page"); var hasFired = false; _cachedTopicRepository.TopicSaved += eventHandler; - _cachedTopicRepository.Save(topic); + await _cachedTopicRepository.Save(topic); _cachedTopicRepository.TopicSaved -= eventHandler; Assert.True(hasFired); @@ -1092,7 +1092,7 @@ public void Save_TopicSavedEvent_IsRaised() { /// /> event is raised. /// [Fact] - public void Save_TopicRenamedEvent_IsRaised() { + public async Task Save_TopicRenamedEvent_IsRaised() { var topic = new Topic("Test", "Page", null, 1); var hasFired = false; @@ -1100,7 +1100,7 @@ public void Save_TopicRenamedEvent_IsRaised() { topic.Key = "New"; _cachedTopicRepository.TopicRenamed += eventHandler; - _cachedTopicRepository.Save(topic); + await _cachedTopicRepository.Save(topic); _cachedTopicRepository.TopicRenamed -= eventHandler; Assert.True(hasFired); @@ -1117,7 +1117,7 @@ public void Save_TopicRenamedEvent_IsRaised() { /// "ITopicRepository.TopicMoved"/> event is raised. /// [Fact] - public void Save_TopicMovedEvent_IsRaised() { + public async Task Save_TopicMovedEvent_IsRaised() { var topic = new Topic("Test", "Page", null, 1); var parent = new Topic("Products", "Page", null, 2); @@ -1126,7 +1126,7 @@ public void Save_TopicMovedEvent_IsRaised() { topic.Parent = parent; _cachedTopicRepository.TopicMoved += eventHandler; - _cachedTopicRepository.Save(topic); + await _cachedTopicRepository.Save(topic); _cachedTopicRepository.TopicMoved -= eventHandler; Assert.True(hasFired); @@ -1145,7 +1145,7 @@ public void Save_TopicMovedEvent_IsRaised() { [Fact] public async Task Save_NewTopic_StampsResolver() { - var parent = _topicRepository.Load("Root:Web:Web_3:Web_3_0").GetAwaiter().GetResult(); + var parent = await _topicRepository.Load("Root:Web:Web_3:Web_3_0"); var topic = new Topic("Test", "Page", parent); await _topicRepository.Save(topic); @@ -1185,9 +1185,9 @@ public async Task Save_NotLoadedChildren_SkipsRecursiveDescent() { /// /> via the 's fill. /// [Fact] - public void EnsureLoaded_ExtendedAttributesNotLoaded_MarksLoaded() { + public async Task EnsureLoaded_ExtendedAttributesNotLoaded_MarksLoaded() { - var topic = _topicRepository.Load(11111).GetAwaiter().GetResult(); + var topic = await _topicRepository.Load(11111); topic!.Attributes.LoadState = LoadState.NotLoaded; topic.EnsureLoaded(TopicPayload.ExtendedAttributes); @@ -1205,9 +1205,9 @@ public void EnsureLoaded_ExtendedAttributesNotLoaded_MarksLoaded() { /// forwarded to the resolver, leaving the already-loaded boundary unchanged. /// [Fact] - public void EnsureLoaded_MixedBoundaries_SkipsLoadedBoundaries() { + public async Task EnsureLoaded_MixedBoundaries_SkipsLoadedBoundaries() { - var topic = _topicRepository.Load(11111).GetAwaiter().GetResult(); + var topic = await _topicRepository.Load(11111); topic!.Attributes.LoadState = LoadState.NotLoaded; Assert.True(topic.IsLoaded(TopicPayload.Children)); @@ -1232,9 +1232,9 @@ public void EnsureLoaded_MixedBoundaries_SkipsLoadedBoundaries() { /// whenever any target is not resident in the single-node topic index it currently uses. /// [Fact] - public void EnsureLoaded_RelationshipsNotLoaded_MarksLoaded() { + public async Task EnsureLoaded_RelationshipsNotLoaded_MarksLoaded() { - var topic = _topicRepository.Load(11111).GetAwaiter().GetResult(); + var topic = await _topicRepository.Load(11111); topic!.Relationships.Deferred.Add(new("_stub", 11111)); topic.EnsureLoaded(TopicPayload.Relationships); @@ -1257,9 +1257,9 @@ public void EnsureLoaded_RelationshipsNotLoaded_MarksLoaded() { /// whenever any target is not resident in the single-node topic index it currently uses. /// [Fact] - public void EnsureLoaded_ReferencesNotLoaded_MarksLoaded() { + public async Task EnsureLoaded_ReferencesNotLoaded_MarksLoaded() { - var topic = _topicRepository.Load(11111).GetAwaiter().GetResult(); + var topic = await _topicRepository.Load(11111); topic!.References.Deferred.Add(new("_stub", 11111)); topic.EnsureLoaded(TopicPayload.References); @@ -1277,9 +1277,9 @@ public void EnsureLoaded_ReferencesNotLoaded_MarksLoaded() { /// "LoadState.Loaded"/> via the 's fill. /// [Fact] - public void IsLoaded_ChildrenNotLoadedState_TriggersEnsureLoaded() { + public async Task IsLoaded_ChildrenNotLoadedState_TriggersEnsureLoaded() { - var topic = _topicRepository.Load(11111).GetAwaiter().GetResult(); + var topic = await _topicRepository.Load(11111); topic!.SetLoadState(TopicPayload.Children, LoadState.NotLoaded); _ = topic.Children; @@ -1297,9 +1297,9 @@ public void IsLoaded_ChildrenNotLoadedState_TriggersEnsureLoaded() { /// resolver being called redundantly. /// [Fact] - public void IsLoaded_ChildrenLoadedState_DoesNotCallResolver() { + public async Task IsLoaded_ChildrenLoadedState_DoesNotCallResolver() { - var topic = _topicRepository.Load(11111).GetAwaiter().GetResult(); + var topic = await _topicRepository.Load(11111); Assert.True(topic!.IsLoaded(TopicPayload.Children)); _ = topic.Children; @@ -1317,9 +1317,9 @@ public void IsLoaded_ChildrenLoadedState_DoesNotCallResolver() { /// via the 's fill. /// [Fact] - public void IsLoaded_RelationshipsNotLoadedState_TriggersEnsureLoaded() { + public async Task IsLoaded_RelationshipsNotLoadedState_TriggersEnsureLoaded() { - var topic = _topicRepository.Load(11111).GetAwaiter().GetResult(); + var topic = await _topicRepository.Load(11111); topic!.Relationships.Deferred.Add(new("_stub", 11111)); _ = topic.Relationships; @@ -1337,9 +1337,9 @@ public void IsLoaded_RelationshipsNotLoadedState_TriggersEnsureLoaded() { /// redundantly. /// [Fact] - public void IsLoaded_RelationshipsLoadedState_DoesNotCallResolver() { + public async Task IsLoaded_RelationshipsLoadedState_DoesNotCallResolver() { - var topic = _topicRepository.Load(11111).GetAwaiter().GetResult(); + var topic = await _topicRepository.Load(11111); Assert.True(topic!.IsLoaded(TopicPayload.Relationships)); _ = topic.Relationships; @@ -1357,9 +1357,9 @@ public void IsLoaded_RelationshipsLoadedState_DoesNotCallResolver() { /// via the 's fill. /// [Fact] - public void IsLoaded_ReferencesNotLoadedState_TriggersEnsureLoaded() { + public async Task IsLoaded_ReferencesNotLoadedState_TriggersEnsureLoaded() { - var topic = _topicRepository.Load(11111).GetAwaiter().GetResult(); + var topic = await _topicRepository.Load(11111); topic!.References.Deferred.Add(new("_stub", 11111)); _ = topic.References; @@ -1377,9 +1377,9 @@ public void IsLoaded_ReferencesNotLoadedState_TriggersEnsureLoaded() { /// redundantly. /// [Fact] - public void IsLoaded_ReferencesLoadedState_DoesNotCallResolver() { + public async Task IsLoaded_ReferencesLoadedState_DoesNotCallResolver() { - var topic = _topicRepository.Load(11111).GetAwaiter().GetResult(); + var topic = await _topicRepository.Load(11111); Assert.True(topic!.IsLoaded(TopicPayload.References)); _ = topic.References; @@ -1397,9 +1397,9 @@ public void IsLoaded_ReferencesLoadedState_DoesNotCallResolver() { /// "LoadState.Loaded"/> via the 's fill. /// [Fact] - public void EnsureLoaded_ChildrenNotLoaded_MarksLoaded() { + public async Task EnsureLoaded_ChildrenNotLoaded_MarksLoaded() { - var topic = _topicRepository.Load(11111).GetAwaiter().GetResult(); + var topic = await _topicRepository.Load(11111); topic!.SetLoadState(TopicPayload.Children, LoadState.NotLoaded); topic.EnsureLoaded(TopicPayload.Children); @@ -1416,14 +1416,14 @@ public void EnsureLoaded_ChildrenNotLoaded_MarksLoaded() { /// /> event is raised. /// [Fact] - public void Move_TopicMovedEvent_IsRaised() { + public async Task Move_TopicMovedEvent_IsRaised() { var topic = new Topic("Test", "Page", null, 1); var parent = new Topic("Products", "Page", null, 2); var hasFired = false; _cachedTopicRepository.TopicMoved += eventHandler; - _cachedTopicRepository.Move(topic, parent); + await _cachedTopicRepository.Move(topic, parent); _cachedTopicRepository.TopicMoved -= eventHandler; Assert.True(hasFired); @@ -1446,10 +1446,10 @@ public void Move_TopicMovedEvent_IsRaised() { /// edge through the full resolver stack. /// [Fact] - public void EnsureLoaded_WithMissingRelationshipTarget_ResolvesAndConnects() { + public async Task EnsureLoaded_WithMissingRelationshipTarget_ResolvesAndConnects() { // Get the root topic from cache; seed a deferred entry to simulate a pending relationship target - var source = _cachedTopicRepository.Load(-1).GetAwaiter().GetResult()!; + var source = (await _cachedTopicRepository.Load(-1))!; source.Relationships.Deferred.Add(new("_stub", 11111)); // Act: EnsureLoaded re-queries, finds the missing target, loads it, and connects the edge @@ -1468,10 +1468,10 @@ public void EnsureLoaded_WithMissingRelationshipTarget_ResolvesAndConnects() { /// "LoadState.Loaded"/> and confirms it returns immediately without re-querying. /// [Fact] - public void EnsureLoaded_Relationships_AlreadyLoaded_SkipsFill() { + public async Task EnsureLoaded_Relationships_AlreadyLoaded_SkipsFill() { // Get the root topic; relationships start as Loaded (Deferred is empty) after initialization - var source = _cachedTopicRepository.Load(-1).GetAwaiter().GetResult()!; + var source = (await _cachedTopicRepository.Load(-1))!; // Act _cachedTopicRepository.EnsureLoaded(source, TopicPayload.Relationships); @@ -1489,7 +1489,7 @@ public void EnsureLoaded_Relationships_AlreadyLoaded_SkipsFill() { /// "ITopicRepository.TopicMoved"/> event is not raised. /// [Fact] - public void Move_SameLocation_EventNotRaised() { + public async Task Move_SameLocation_EventNotRaised() { var parent = new Topic("Parent", "Page", null, 1); var sibling = new Topic("Sibling", "Page", parent, 2); @@ -1497,7 +1497,7 @@ public void Move_SameLocation_EventNotRaised() { var hasFired = false; _cachedTopicRepository.TopicMoved += eventHandler; - _cachedTopicRepository.Move(topic, parent, sibling); + await _cachedTopicRepository.Move(topic, parent, sibling); _cachedTopicRepository.TopicMoved -= eventHandler; Assert.False(hasFired); From 688c69b730209c1328f6737d06947d1b38d8cc9d Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Wed, 8 Jul 2026 21:27:53 -0700 Subject: [PATCH 115/337] Prefer collection expressions (cont.) This continues a change that was first implemented narrowly (aff64914). --- .../ValidateTopicAttributeTest.cs | 2 +- .../Controllers/SitemapController.cs | 2 +- .../TopicRepositoryExtensions.cs | 4 +- .../TopicViewResultExecutor.cs | 2 +- OnTopic.Data.Caching/CachedTopicRepository.cs | 2 +- OnTopic.Data.Sql/SqlDataReaderExtensions.cs | 4 +- OnTopic.Tests/KeyedTopicCollectionTest.cs | 2 +- OnTopic.Tests/MemberAccessorTest.cs | 2 +- OnTopic.Tests/TypeLookupServiceTest.cs | 41 +++++++------------ .../ReadOnlyKeyedTopicCollection{T}.cs | 2 +- .../Collections/ReadOnlyTopicCollection.cs | 2 +- .../Specialized/ReadOnlyTopicMultiMap.cs | 2 +- OnTopic/Internal/Reflection/MemberAccessor.cs | 4 +- .../HierarchicalTopicMappingService{T}.cs | 4 +- .../Reverse/ReverseTopicMappingService.cs | 30 +++++++------- OnTopic/Mapping/TopicMappingService.cs | 12 +++--- OnTopic/Repositories/TopicRepository.cs | 2 +- 17 files changed, 54 insertions(+), 65 deletions(-) diff --git a/OnTopic.AspNetCore.Mvc.Tests/ValidateTopicAttributeTest.cs b/OnTopic.AspNetCore.Mvc.Tests/ValidateTopicAttributeTest.cs index 00068ccb..896fa295 100644 --- a/OnTopic.AspNetCore.Mvc.Tests/ValidateTopicAttributeTest.cs +++ b/OnTopic.AspNetCore.Mvc.Tests/ValidateTopicAttributeTest.cs @@ -43,7 +43,7 @@ public static ActionExecutingContext GetActionExecutingContext(Controller contro var actionExecutingContext = new ActionExecutingContext( actionContext, - new List(), + [], new Dictionary(), controller ); diff --git a/OnTopic.AspNetCore.Mvc/Controllers/SitemapController.cs b/OnTopic.AspNetCore.Mvc/Controllers/SitemapController.cs index 4acbb9de..dd92fc36 100644 --- a/OnTopic.AspNetCore.Mvc/Controllers/SitemapController.cs +++ b/OnTopic.AspNetCore.Mvc/Controllers/SitemapController.cs @@ -168,7 +168,7 @@ private List AddTopic(Topic topic, bool includeMetadata = false) { /*-------------------------------------------------------------------------------------------------------------------------- | Establish return collection \-------------------------------------------------------------------------------------------------------------------------*/ - var topics = new List(); + List topics = []; /*-------------------------------------------------------------------------------------------------------------------------- | Validate topic diff --git a/OnTopic.AspNetCore.Mvc/TopicRepositoryExtensions.cs b/OnTopic.AspNetCore.Mvc/TopicRepositoryExtensions.cs index 353e7a0e..fcda1543 100644 --- a/OnTopic.AspNetCore.Mvc/TopicRepositoryExtensions.cs +++ b/OnTopic.AspNetCore.Mvc/TopicRepositoryExtensions.cs @@ -59,13 +59,13 @@ RouteData routeData | case particular routes aren't present. That said, if they are defined, but should be excluded from a fallback, then | that path does need to be defined—thus e.g. {area}/{controller}/{path}. \-------------------------------------------------------------------------------------------------------------------------*/ - var paths = new List() { + List paths = [ cleanPath($"{rootTopic}/{path}"), cleanPath($"{area}/{controller}/{action}/{path}"), cleanPath($"{area}/{controller}/{path}"), cleanPath($"{area}/{action}/{path}"), cleanPath($"{area}/{path}") - }; + ]; /*-------------------------------------------------------------------------------------------------------------------------- | Load by path diff --git a/OnTopic.AspNetCore.Mvc/TopicViewResultExecutor.cs b/OnTopic.AspNetCore.Mvc/TopicViewResultExecutor.cs index c5aa032d..c0006f73 100644 --- a/OnTopic.AspNetCore.Mvc/TopicViewResultExecutor.cs +++ b/OnTopic.AspNetCore.Mvc/TopicViewResultExecutor.cs @@ -75,7 +75,7 @@ public ViewEngineResult FindView(ActionContext actionContext, TopicViewResult vi var viewEngine = viewResult.ViewEngine?? ViewEngine; var requestContext = actionContext.HttpContext.Request; var view = (ViewEngineResult?)null; - var searchedPaths = new List(); + List searchedPaths = []; /*-------------------------------------------------------------------------------------------------------------------------- | Cache content type as route variable diff --git a/OnTopic.Data.Caching/CachedTopicRepository.cs b/OnTopic.Data.Caching/CachedTopicRepository.cs index 596ab042..20ed7fd8 100644 --- a/OnTopic.Data.Caching/CachedTopicRepository.cs +++ b/OnTopic.Data.Caching/CachedTopicRepository.cs @@ -493,7 +493,7 @@ private void IndexTopic(Topic topic) { private void MergeIntoCache(Topic loaded) { // Build the ancestor chain from the leaf up to the root (leaf first) - var chain = new List(); + List chain = []; for (var node = loaded; node is not null; node = node.Parent) { chain.Add(node); } diff --git a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs index f941c7f6..d58cd9eb 100644 --- a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs +++ b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs @@ -74,7 +74,7 @@ internal static class SqlDataReaderExtensions { \-------------------------------------------------------------------------------------------------------------------------*/ var topics = referenceTopic is not null? referenceTopic.GetRootTopic().GetTopicIndex() : new(); var rootTopic = (Topic?)null; - var preExistingIds = new HashSet(topics.Keys); + HashSet preExistingIds = [..topics.Keys]; var hasChildrenMap = new Dictionary(); /*-------------------------------------------------------------------------------------------------------------------------- @@ -112,7 +112,7 @@ internal static class SqlDataReaderExtensions { // ancestors have exactly one child loaded (from the ancestor crawl), but may have more; as such, they will be marked as // NotLoaded. Note: An ancestor whose sole database child is part of the ancestor chain is still marked NotLoaded, since we // don't have enough information to verify that. This is an unlikely scenario, but will cost one extra round-trip to verify. - var ancestorIds = new HashSet(); + HashSet ancestorIds = []; if (topics.TryGetValue(seedTopicId, out var seedTopic)) { var ancestor = seedTopic.Parent; while (ancestor is not null && hasChildrenMap.ContainsKey(ancestor.Id)) { diff --git a/OnTopic.Tests/KeyedTopicCollectionTest.cs b/OnTopic.Tests/KeyedTopicCollectionTest.cs index 72c88e53..60f6ee48 100644 --- a/OnTopic.Tests/KeyedTopicCollectionTest.cs +++ b/OnTopic.Tests/KeyedTopicCollectionTest.cs @@ -45,7 +45,7 @@ public void SetTopic_Indexer_ReturnsTopic() { [Fact] public void Constructor_IEnumerable_SeedsTopics() { - var topics = new List(); + List topics = []; for (var i = 0; i < 10; i++) { topics.Add(new("Topic" + i, "Page")); diff --git a/OnTopic.Tests/MemberAccessorTest.cs b/OnTopic.Tests/MemberAccessorTest.cs index f69738b4..de25bfef 100644 --- a/OnTopic.Tests/MemberAccessorTest.cs +++ b/OnTopic.Tests/MemberAccessorTest.cs @@ -396,7 +396,7 @@ public void IsValid_InvalidSetterMethod_ReturnsFalse() public void IsValid_Constructor_ReturnsFalse() { var type = typeof(MemberAccessorViewModel); - var memberInfo = type.GetConstructor(Array.Empty())!; + var memberInfo = type.GetConstructor([])!; Assert.NotNull(memberInfo); Assert.False(MemberAccessor.IsValid(memberInfo)); diff --git a/OnTopic.Tests/TypeLookupServiceTest.cs b/OnTopic.Tests/TypeLookupServiceTest.cs index 2caba245..ff59831a 100644 --- a/OnTopic.Tests/TypeLookupServiceTest.cs +++ b/OnTopic.Tests/TypeLookupServiceTest.cs @@ -33,11 +33,11 @@ public class TypeLookupServiceTest { [Fact] public void TypeCollection_Constructor_ContainsUniqueTypes() { - var topics = new List { + List topics = [ typeof(BasicTopicBindingModel), typeof(CustomTopic), typeof(CustomTopic) - }; + ]; var typeCollection = new TypeCollection(topics); Assert.Equal(2, typeCollection.Count); @@ -56,9 +56,7 @@ public void TypeCollection_Constructor_ContainsUniqueTypes() { [Fact] public void StaticLookupService_TryAdd_ReturnsExpected() { - var topics = new List { - typeof(CustomTopic) - }; + List topics = [typeof(CustomTopic)]; var lookupService = new DummyStaticTypeLookupService(topics); Assert.False(lookupService.TryAdd(typeof(CustomTopic))); @@ -76,10 +74,7 @@ public void StaticLookupService_TryAdd_ReturnsExpected() { [Fact] public void StaticLookupService_Lookup_ReturnsFallback() { - var topics = new List { - typeof(AscendentTopicViewModel), - typeof(FallbackViewModel) - }; + List topics = [typeof(AscendentTopicViewModel), typeof(FallbackViewModel)]; var lookupService = new StaticTypeLookupService(topics); Assert.Equal(typeof(FallbackViewModel), lookupService.Lookup(nameof(EmptyViewModel), nameof(FallbackViewModel))); @@ -136,21 +131,17 @@ public void DynamicTypeLookupService_Predicate_ReturnsExpected() { [Fact] public void CompositeTypeLookupService_Lookup_ReturnsFallback() { - var lookupService1 = new StaticTypeLookupService( - new List { - typeof(EmptyViewModel), - typeof(FallbackViewModel), - typeof(Internal.Diagnostics.Contract) - } - ); + var lookupService1 = new StaticTypeLookupService([ + typeof(EmptyViewModel), + typeof(FallbackViewModel), + typeof(Contract) + ]); - var lookupService2 = new StaticTypeLookupService( - new List { - typeof(AscendentTopicViewModel), - typeof(FallbackViewModel), - typeof(System.Diagnostics.Contracts.Contract) - } - ); + var lookupService2 = new StaticTypeLookupService([ + typeof(AscendentTopicViewModel), + typeof(FallbackViewModel), + typeof(System.Diagnostics.Contracts.Contract) + ]); var lookupService = new CompositeTypeLookupService(lookupService1, lookupService2); @@ -170,9 +161,7 @@ public void CompositeTypeLookupService_Lookup_ReturnsFallback() { [Fact] public void DefaultTopicLookupService_Lookup_ReturnsExpected() { - var topics = new List { - typeof(CustomTopic) - }; + List topics = [typeof(CustomTopic)]; var lookupService = new DefaultTopicLookupService(topics); Assert.Equal(typeof(AttributeDescriptor), lookupService.Lookup(nameof(AttributeDescriptor))); diff --git a/OnTopic/Collections/ReadOnlyKeyedTopicCollection{T}.cs b/OnTopic/Collections/ReadOnlyKeyedTopicCollection{T}.cs index 30d45eff..891519cd 100644 --- a/OnTopic/Collections/ReadOnlyKeyedTopicCollection{T}.cs +++ b/OnTopic/Collections/ReadOnlyKeyedTopicCollection{T}.cs @@ -27,7 +27,7 @@ public class ReadOnlyKeyedTopicCollection : ReadOnlyCollection where T : T /// Establishes a new based on an existing . /// /// The underlying . - public ReadOnlyKeyedTopicCollection(IList? innerCollection = null) : base(innerCollection?? new List()) { + public ReadOnlyKeyedTopicCollection(IList? innerCollection = null) : base(innerCollection ?? []) { _innerCollection = innerCollection as KeyedTopicCollection?? new(innerCollection); } diff --git a/OnTopic/Collections/ReadOnlyTopicCollection.cs b/OnTopic/Collections/ReadOnlyTopicCollection.cs index 2de234fe..86eec86d 100644 --- a/OnTopic/Collections/ReadOnlyTopicCollection.cs +++ b/OnTopic/Collections/ReadOnlyTopicCollection.cs @@ -23,7 +23,7 @@ public class ReadOnlyTopicCollection : ReadOnlyCollection { /// /// The underlying . [ExcludeFromCodeCoverage] - public ReadOnlyTopicCollection(IList? innerCollection = null) : base(innerCollection?? new List()) { + public ReadOnlyTopicCollection(IList? innerCollection = null) : base(innerCollection ?? []) { } /*============================================================================================================================ diff --git a/OnTopic/Collections/Specialized/ReadOnlyTopicMultiMap.cs b/OnTopic/Collections/Specialized/ReadOnlyTopicMultiMap.cs index b040cf9b..beb1dd7a 100644 --- a/OnTopic/Collections/Specialized/ReadOnlyTopicMultiMap.cs +++ b/OnTopic/Collections/Specialized/ReadOnlyTopicMultiMap.cs @@ -101,7 +101,7 @@ public ReadOnlyTopicCollection GetValues(string key) { if (Contains(key)) { return new(Source[key].Values); } - return new(new List()); + return new([]); } /// diff --git a/OnTopic/Internal/Reflection/MemberAccessor.cs b/OnTopic/Internal/Reflection/MemberAccessor.cs index 3d3fd76e..9aac49d8 100644 --- a/OnTopic/Internal/Reflection/MemberAccessor.cs +++ b/OnTopic/Internal/Reflection/MemberAccessor.cs @@ -233,12 +233,12 @@ internal void Validate(object target) { /// Provides a list of member names automatically generated by the compiler for record types, but which aren't /// relevant to mapping and should be excluded. /// - private static List ExcludedMembers { get; } = new List() { + private static List ExcludedMembers { get; } = [ "EqualityContract", "GetHashCode", "ToString", "$" - }; + ]; /*============================================================================================================================ diff --git a/OnTopic/Mapping/Hierarchical/HierarchicalTopicMappingService{T}.cs b/OnTopic/Mapping/Hierarchical/HierarchicalTopicMappingService{T}.cs index 12646125..797fd2cc 100644 --- a/OnTopic/Mapping/Hierarchical/HierarchicalTopicMappingService{T}.cs +++ b/OnTopic/Mapping/Hierarchical/HierarchicalTopicMappingService{T}.cs @@ -145,8 +145,8 @@ private static int DistanceFromRoot(Topic sourceTopic) { /*-------------------------------------------------------------------------------------------------------------------------- | Establish variables \-------------------------------------------------------------------------------------------------------------------------*/ - var taskQueue = new List>(); - var children = new List(); + List> taskQueue = []; + List children = []; var viewModel = (T?)null; /*-------------------------------------------------------------------------------------------------------------------------- diff --git a/OnTopic/Mapping/Reverse/ReverseTopicMappingService.cs b/OnTopic/Mapping/Reverse/ReverseTopicMappingService.cs index c48bddaa..9781fe47 100644 --- a/OnTopic/Mapping/Reverse/ReverseTopicMappingService.cs +++ b/OnTopic/Mapping/Reverse/ReverseTopicMappingService.cs @@ -201,7 +201,7 @@ public ReverseTopicMappingService(ITopicRepository topicRepository) { /*-------------------------------------------------------------------------------------------------------------------------- | Loop through properties, mapping each one \-------------------------------------------------------------------------------------------------------------------------*/ - var taskQueue = new List(); + List taskQueue = []; foreach (var property in typeAccessor.GetMembers(MemberTypes.Property)) { taskQueue.Add(SetPropertyAsync(source, target, property, attributePrefix)); } @@ -344,7 +344,7 @@ private static void SetScalarValue( | Fall back to default, if configured \-------------------------------------------------------------------------------------------------------------------------*/ if (String.IsNullOrEmpty(attributeValue) && configuration.DefaultValue is not null) { - attributeValue = configuration.DefaultValue.ToString(); + attributeValue = configuration.DefaultValue.ToString(); } /*-------------------------------------------------------------------------------------------------------------------------- @@ -389,9 +389,9 @@ private async Task SetRelationships( /*-------------------------------------------------------------------------------------------------------------------------- | Retrieve source list \-------------------------------------------------------------------------------------------------------------------------*/ - var sourceList = (IList?)memberAccessor.GetValue(source); + var sourceList = (IList?)memberAccessor.GetValue(source); - sourceList ??= new List(); + sourceList ??= new List(); /*-------------------------------------------------------------------------------------------------------------------------- | Clear existing relationships @@ -402,7 +402,7 @@ private async Task SetRelationships( | Set relationships for each \-------------------------------------------------------------------------------------------------------------------------*/ foreach (IAssociatedTopicBindingModel relationship in sourceList) { - var targetTopic = await _topicRepository.Load(relationship.UniqueKey, target).ConfigureAwait(false); + var targetTopic = await _topicRepository.Load(relationship.UniqueKey, target).ConfigureAwait(false); if (targetTopic is null) { throw new MappingModelValidationException( $"The relationship '{relationship.UniqueKey}' mapped in the '{memberAccessor.Name}' property could not be " + @@ -442,15 +442,15 @@ private async Task SetNestedTopicsAsync( /*-------------------------------------------------------------------------------------------------------------------------- | Retrieve source list \-------------------------------------------------------------------------------------------------------------------------*/ - var sourceList = (IList?)memberAccessor.GetValue(source) ?? new List(); + var sourceList = (IList?)memberAccessor.GetValue(source) ?? new List(); /*-------------------------------------------------------------------------------------------------------------------------- | Establish target collection to store mapped topics \-------------------------------------------------------------------------------------------------------------------------*/ - var container = target.Children.GetValue(configuration.GetCompositeAttributeKey(attributePrefix)); + var container = target.Children.GetValue(configuration.GetCompositeAttributeKey(attributePrefix)); if (container is null) { - container = TopicFactory.Create(configuration.GetCompositeAttributeKey(attributePrefix), "List", target); - container.IsHidden = true; + container = TopicFactory.Create(configuration.GetCompositeAttributeKey(attributePrefix), "List", target); + container.IsHidden = true; } /*-------------------------------------------------------------------------------------------------------------------------- @@ -488,7 +488,7 @@ private async Task SetReference( /*-------------------------------------------------------------------------------------------------------------------------- | Retrieve source value \-------------------------------------------------------------------------------------------------------------------------*/ - var modelReference = (IAssociatedTopicBindingModel?)memberAccessor.GetValue(source); + var modelReference = (IAssociatedTopicBindingModel?)memberAccessor.GetValue(source); /*-------------------------------------------------------------------------------------------------------------------------- | Provide error handling @@ -503,7 +503,7 @@ private async Task SetReference( /*-------------------------------------------------------------------------------------------------------------------------- | Identify target value \-------------------------------------------------------------------------------------------------------------------------*/ - var topicReference = await _topicRepository.Load(modelReference.UniqueKey, target).ConfigureAwait(false); + var topicReference = await _topicRepository.Load(modelReference.UniqueKey, target).ConfigureAwait(false); /*-------------------------------------------------------------------------------------------------------------------------- | Provide error handling @@ -543,7 +543,7 @@ KeyedTopicCollection targetList /*-------------------------------------------------------------------------------------------------------------------------- | Queue up mapping tasks \-------------------------------------------------------------------------------------------------------------------------*/ - var taskQueue = new List>(); + List> taskQueue = []; //Map child binding model to target collection on the target foreach (ITopicBindingModel childBindingModel in sourceList) { @@ -559,7 +559,7 @@ KeyedTopicCollection targetList /*-------------------------------------------------------------------------------------------------------------------------- | Remove orphaned topics \-------------------------------------------------------------------------------------------------------------------------*/ - foreach (var childTopic in targetList.ToArray()) { + foreach (var childTopic in targetList.ToArray()) { if (sourceList.Cast().Any(model => model.Key == childTopic.Key)) { continue; } @@ -570,9 +570,9 @@ KeyedTopicCollection targetList | Process mapping tasks \-------------------------------------------------------------------------------------------------------------------------*/ while (taskQueue.Count > 0) { - var topicTask = await Task.WhenAny(taskQueue).ConfigureAwait(false); + var topicTask = await Task.WhenAny(taskQueue).ConfigureAwait(false); taskQueue.Remove(topicTask); - var topic = await topicTask.ConfigureAwait(false); + var topic = await topicTask.ConfigureAwait(false); if (topic is not null && !targetList.Contains(topic.Key)) { targetList.Add(topic); } diff --git a/OnTopic/Mapping/TopicMappingService.cs b/OnTopic/Mapping/TopicMappingService.cs index 11165068..23dc27bf 100644 --- a/OnTopic/Mapping/TopicMappingService.cs +++ b/OnTopic/Mapping/TopicMappingService.cs @@ -246,7 +246,7 @@ public class TopicMappingService(ITopicRepository topicRepository, ITypeLookupSe /*-------------------------------------------------------------------------------------------------------------------------- | Loop through properties, mapping each one \-------------------------------------------------------------------------------------------------------------------------*/ - var propertyQueue = new List(); + List propertyQueue = []; var mappedParameters = parameters.Select(p => p.Name).Union(attributeArguments.Select(a => a.Key)).ToArray(); foreach (var property in typeAccessor.GetMembers(MemberTypes.Property)) { @@ -347,7 +347,7 @@ private async Task MapAsync( /*-------------------------------------------------------------------------------------------------------------------------- | Loop through properties, mapping each one \-------------------------------------------------------------------------------------------------------------------------*/ - var taskQueue = new List(); + List taskQueue = []; var typeAccessor = TypeAccessorCache.GetTypeAccessor(target.GetType()); foreach (var property in typeAccessor.GetMembers(MemberTypes.Property)) { @@ -426,8 +426,8 @@ private async Task MapAsync( var sourceList = await GetSourceCollectionAsync(source, associations, parameter, attributePrefix).ConfigureAwait(false); var targetList = InitializeCollection(targetType); - if (sourceList is null || targetList is null) { - return (IList?)null; + if (targetList is null) { + return null; } await PopulateTargetCollectionAsync(sourceList, targetList, parameter, cache).ConfigureAwait(false); @@ -881,7 +881,7 @@ sourcePropertyValue[0] is Topic | Handle flattening of children \-------------------------------------------------------------------------------------------------------------------------*/ if (configuration.FlattenChildren) { - var flattenedList = new List(); + List flattenedList = []; listSource.ToList().ForEach(t => FlattenTopicGraph(t, flattenedList)); listSource = flattenedList; } @@ -940,7 +940,7 @@ MappedTopicCache cache /*-------------------------------------------------------------------------------------------------------------------------- | Queue up mapping tasks \-------------------------------------------------------------------------------------------------------------------------*/ - var taskQueue = new List>(); + List> taskQueue = []; foreach (var childTopic in sourceList) { diff --git a/OnTopic/Repositories/TopicRepository.cs b/OnTopic/Repositories/TopicRepository.cs index 830130a6..d3062a6a 100644 --- a/OnTopic/Repositories/TopicRepository.cs +++ b/OnTopic/Repositories/TopicRepository.cs @@ -744,7 +744,7 @@ protected IEnumerable GetAttributes( /*-------------------------------------------------------------------------------------------------------------------------- | Get indexed attributes \-------------------------------------------------------------------------------------------------------------------------*/ - var attributes = new List(); + List attributes = []; foreach (var attributeValue in topic.Attributes) { From 5c6bd856d9205624329c59064054f39f5785363e Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Wed, 8 Jul 2026 22:05:40 -0700 Subject: [PATCH 116/337] Prefer implicit constructors if type known (cont.) This continues a one-off implementation previously (56379ac2). --- .../_filters/TopicResponseCacheAttribute.cs | 2 +- OnTopic.Data.Sql/Models/AttributeValuesDataTable.cs | 4 ++-- OnTopic.Data.Sql/Models/TopicListDataTable.cs | 2 +- OnTopic.Data.Sql/Models/TopicReferencesDataTable.cs | 4 ++-- OnTopic.Tests/Fixtures/TypeAccessorFixture.cs | 2 +- OnTopic.Tests/Schemas/AttributesDataTable.cs | 8 ++++---- OnTopic.Tests/Schemas/ExtendedAttributesDataTable.cs | 6 +++--- OnTopic.Tests/Schemas/RelationshipsDataTable.cs | 10 +++++----- OnTopic.Tests/Schemas/TopicReferencesDataTable.cs | 8 ++++---- OnTopic.Tests/Schemas/TopicsDataTable.cs | 12 ++++++------ OnTopic.Tests/Schemas/VersionHistoryDataTable.cs | 4 ++-- OnTopic.Tests/TopicRepositoryBaseTest.cs | 2 +- 12 files changed, 32 insertions(+), 32 deletions(-) diff --git a/OnTopic.AspNetCore.Mvc/_filters/TopicResponseCacheAttribute.cs b/OnTopic.AspNetCore.Mvc/_filters/TopicResponseCacheAttribute.cs index ff5b15e5..8ba420f4 100644 --- a/OnTopic.AspNetCore.Mvc/_filters/TopicResponseCacheAttribute.cs +++ b/OnTopic.AspNetCore.Mvc/_filters/TopicResponseCacheAttribute.cs @@ -76,7 +76,7 @@ public override void OnActionExecuting(ActionExecutingContext context) { _defaultCacheProfile ??= controller.TopicRepository.Load("Configuration:CacheProfiles:Default").GetAwaiter().GetResult(); // Ensure the above lookup is only performed once per application - _defaultCacheProfile ??= new Topic("ImplicitDefault", "CacheProfile"); + _defaultCacheProfile ??= new("ImplicitDefault", "CacheProfile"); /*-------------------------------------------------------------------------------------------------------------------------- | Identify cache profile diff --git a/OnTopic.Data.Sql/Models/AttributeValuesDataTable.cs b/OnTopic.Data.Sql/Models/AttributeValuesDataTable.cs index fd3d86cb..35ec53fa 100644 --- a/OnTopic.Data.Sql/Models/AttributeValuesDataTable.cs +++ b/OnTopic.Data.Sql/Models/AttributeValuesDataTable.cs @@ -29,7 +29,7 @@ internal AttributeValuesDataTable() { | COLUMN: Attribute Key \-------------------------------------------------------------------------------------------------------------------------*/ Columns.Add( - new DataColumn("AttributeKey") { + new("AttributeKey") { MaxLength = 128 } ); @@ -38,7 +38,7 @@ internal AttributeValuesDataTable() { | COLUMN: Attribute Value \-------------------------------------------------------------------------------------------------------------------------*/ Columns.Add( - new DataColumn("AttributeRecord") { + new("AttributeRecord") { MaxLength = 255 } ); diff --git a/OnTopic.Data.Sql/Models/TopicListDataTable.cs b/OnTopic.Data.Sql/Models/TopicListDataTable.cs index 38715b44..c41b05d1 100644 --- a/OnTopic.Data.Sql/Models/TopicListDataTable.cs +++ b/OnTopic.Data.Sql/Models/TopicListDataTable.cs @@ -27,7 +27,7 @@ internal TopicListDataTable() { | COLUMN: Topic ID \-------------------------------------------------------------------------------------------------------------------------*/ Columns.Add( - new DataColumn("TopicID", typeof(int)) + new("TopicID", typeof(int)) ); } diff --git a/OnTopic.Data.Sql/Models/TopicReferencesDataTable.cs b/OnTopic.Data.Sql/Models/TopicReferencesDataTable.cs index b3d98c15..e1e934f2 100644 --- a/OnTopic.Data.Sql/Models/TopicReferencesDataTable.cs +++ b/OnTopic.Data.Sql/Models/TopicReferencesDataTable.cs @@ -27,7 +27,7 @@ internal TopicReferencesDataTable() { | COLUMN: Reference Key \-------------------------------------------------------------------------------------------------------------------------*/ Columns.Add( - new DataColumn("ReferenceKey") { + new("ReferenceKey") { MaxLength = 128 } ); @@ -36,7 +36,7 @@ internal TopicReferencesDataTable() { | COLUMN: Topic ID \-------------------------------------------------------------------------------------------------------------------------*/ Columns.Add( - new DataColumn("TopicID", typeof(int)) + new("TopicID", typeof(int)) ); } diff --git a/OnTopic.Tests/Fixtures/TypeAccessorFixture.cs b/OnTopic.Tests/Fixtures/TypeAccessorFixture.cs index fa290a71..80d294f5 100644 --- a/OnTopic.Tests/Fixtures/TypeAccessorFixture.cs +++ b/OnTopic.Tests/Fixtures/TypeAccessorFixture.cs @@ -24,7 +24,7 @@ public TypeAccessorFixture() { /*-------------------------------------------------------------------------------------------------------------------------- | Create type accessor \-------------------------------------------------------------------------------------------------------------------------*/ - TypeAccessor = new TypeAccessor(typeof(T)); + TypeAccessor = new(typeof(T)); } diff --git a/OnTopic.Tests/Schemas/AttributesDataTable.cs b/OnTopic.Tests/Schemas/AttributesDataTable.cs index b4e090d3..05e7f2b5 100644 --- a/OnTopic.Tests/Schemas/AttributesDataTable.cs +++ b/OnTopic.Tests/Schemas/AttributesDataTable.cs @@ -32,7 +32,7 @@ public AttributesDataTable() : base("Attributes") { /*-------------------------------------------------------------------------------------------------------------------------- | Add TopicId column \-------------------------------------------------------------------------------------------------------------------------*/ - Columns.Add(new DataColumn() { + Columns.Add(new() { DataType = typeof(int), ColumnName = "TopicId", Unique = true @@ -41,7 +41,7 @@ public AttributesDataTable() : base("Attributes") { /*-------------------------------------------------------------------------------------------------------------------------- | Add AttributeKey column \-------------------------------------------------------------------------------------------------------------------------*/ - Columns.Add(new DataColumn() { + Columns.Add(new() { DataType = typeof(string), ColumnName = "AttributeKey" }); @@ -49,7 +49,7 @@ public AttributesDataTable() : base("Attributes") { /*-------------------------------------------------------------------------------------------------------------------------- | Add AttributeValue column \-------------------------------------------------------------------------------------------------------------------------*/ - Columns.Add(new DataColumn() { + Columns.Add(new() { DataType = typeof(string), ColumnName = "AttributeValue", AllowDBNull = true @@ -58,7 +58,7 @@ public AttributesDataTable() : base("Attributes") { /*-------------------------------------------------------------------------------------------------------------------------- | Add Version column \-------------------------------------------------------------------------------------------------------------------------*/ - Columns.Add(new DataColumn() { + Columns.Add(new() { DataType = typeof(DateTime), ColumnName = "Version" }); diff --git a/OnTopic.Tests/Schemas/ExtendedAttributesDataTable.cs b/OnTopic.Tests/Schemas/ExtendedAttributesDataTable.cs index 136e6f9d..54e0f131 100644 --- a/OnTopic.Tests/Schemas/ExtendedAttributesDataTable.cs +++ b/OnTopic.Tests/Schemas/ExtendedAttributesDataTable.cs @@ -33,7 +33,7 @@ public ExtendedAttributesDataTable() : base("ExtendedAttributes") { /*-------------------------------------------------------------------------------------------------------------------------- | Add TopicId column \-------------------------------------------------------------------------------------------------------------------------*/ - Columns.Add(new DataColumn() { + Columns.Add(new() { DataType = typeof(int), ColumnName = "TopicId", Unique = true @@ -42,7 +42,7 @@ public ExtendedAttributesDataTable() : base("ExtendedAttributes") { /*-------------------------------------------------------------------------------------------------------------------------- | Add AttributesXml column \-------------------------------------------------------------------------------------------------------------------------*/ - Columns.Add(new DataColumn() { + Columns.Add(new() { DataType = typeof(XmlDocument), ColumnName = "AttributesXml" }); @@ -50,7 +50,7 @@ public ExtendedAttributesDataTable() : base("ExtendedAttributes") { /*-------------------------------------------------------------------------------------------------------------------------- | Add Version column \-------------------------------------------------------------------------------------------------------------------------*/ - Columns.Add(new DataColumn() { + Columns.Add(new() { DataType = typeof(DateTime), ColumnName = "Version" }); diff --git a/OnTopic.Tests/Schemas/RelationshipsDataTable.cs b/OnTopic.Tests/Schemas/RelationshipsDataTable.cs index e312e548..d3174cf8 100644 --- a/OnTopic.Tests/Schemas/RelationshipsDataTable.cs +++ b/OnTopic.Tests/Schemas/RelationshipsDataTable.cs @@ -32,7 +32,7 @@ public RelationshipsDataTable() : base("Relationships") { /*-------------------------------------------------------------------------------------------------------------------------- | Add Source_TopicId column \-------------------------------------------------------------------------------------------------------------------------*/ - Columns.Add(new DataColumn() { + Columns.Add(new() { DataType = typeof(int), ColumnName = "Source_TopicId", Unique = true @@ -41,7 +41,7 @@ public RelationshipsDataTable() : base("Relationships") { /*-------------------------------------------------------------------------------------------------------------------------- | Add RelationshipKey column \-------------------------------------------------------------------------------------------------------------------------*/ - Columns.Add(new DataColumn() { + Columns.Add(new() { DataType = typeof(string), ColumnName = "RelationshipKey" }); @@ -49,7 +49,7 @@ public RelationshipsDataTable() : base("Relationships") { /*-------------------------------------------------------------------------------------------------------------------------- | Add Target_TopicId column \-------------------------------------------------------------------------------------------------------------------------*/ - Columns.Add(new DataColumn() { + Columns.Add(new() { DataType = typeof(int), ColumnName = "Target_TopicId" }); @@ -57,7 +57,7 @@ public RelationshipsDataTable() : base("Relationships") { /*-------------------------------------------------------------------------------------------------------------------------- | Add IsDeleted column \-------------------------------------------------------------------------------------------------------------------------*/ - Columns.Add(new DataColumn() { + Columns.Add(new() { DataType = typeof(bool), ColumnName = "IsDeleted" }); @@ -65,7 +65,7 @@ public RelationshipsDataTable() : base("Relationships") { /*-------------------------------------------------------------------------------------------------------------------------- | Add ParentId column \-------------------------------------------------------------------------------------------------------------------------*/ - Columns.Add(new DataColumn() { + Columns.Add(new() { DataType = typeof(DateTime), ColumnName = "Version" }); diff --git a/OnTopic.Tests/Schemas/TopicReferencesDataTable.cs b/OnTopic.Tests/Schemas/TopicReferencesDataTable.cs index 4758b5e9..892300bf 100644 --- a/OnTopic.Tests/Schemas/TopicReferencesDataTable.cs +++ b/OnTopic.Tests/Schemas/TopicReferencesDataTable.cs @@ -32,7 +32,7 @@ public TopicReferencesDataTable() : base("TopicReferences") { /*-------------------------------------------------------------------------------------------------------------------------- | Add Source_TopicId column \-------------------------------------------------------------------------------------------------------------------------*/ - Columns.Add(new DataColumn() { + Columns.Add(new() { DataType = typeof(int), ColumnName = "Source_TopicId", Unique = true @@ -41,7 +41,7 @@ public TopicReferencesDataTable() : base("TopicReferences") { /*-------------------------------------------------------------------------------------------------------------------------- | Add RelationshipKey column \-------------------------------------------------------------------------------------------------------------------------*/ - Columns.Add(new DataColumn() { + Columns.Add(new() { DataType = typeof(string), ColumnName = "ReferenceKey" }); @@ -49,7 +49,7 @@ public TopicReferencesDataTable() : base("TopicReferences") { /*-------------------------------------------------------------------------------------------------------------------------- | Add Target_TopicId column \-------------------------------------------------------------------------------------------------------------------------*/ - Columns.Add(new DataColumn() { + Columns.Add(new() { DataType = typeof(int), ColumnName = "Target_TopicId", AllowDBNull = true @@ -58,7 +58,7 @@ public TopicReferencesDataTable() : base("TopicReferences") { /*-------------------------------------------------------------------------------------------------------------------------- | Add ParentId column \-------------------------------------------------------------------------------------------------------------------------*/ - Columns.Add(new DataColumn() { + Columns.Add(new() { DataType = typeof(DateTime), ColumnName = "Version" }); diff --git a/OnTopic.Tests/Schemas/TopicsDataTable.cs b/OnTopic.Tests/Schemas/TopicsDataTable.cs index d91d93cd..92136677 100644 --- a/OnTopic.Tests/Schemas/TopicsDataTable.cs +++ b/OnTopic.Tests/Schemas/TopicsDataTable.cs @@ -32,7 +32,7 @@ public TopicsDataTable() : base("Topics") { /*-------------------------------------------------------------------------------------------------------------------------- | Add TopicId column \-------------------------------------------------------------------------------------------------------------------------*/ - Columns.Add(new DataColumn() { + Columns.Add(new() { DataType = typeof(int), ColumnName = "TopicId", Unique = true @@ -41,7 +41,7 @@ public TopicsDataTable() : base("Topics") { /*-------------------------------------------------------------------------------------------------------------------------- | Add TopicKey column \-------------------------------------------------------------------------------------------------------------------------*/ - Columns.Add(new DataColumn() { + Columns.Add(new() { DataType = typeof(string), ColumnName = "TopicKey" }); @@ -49,7 +49,7 @@ public TopicsDataTable() : base("Topics") { /*-------------------------------------------------------------------------------------------------------------------------- | Add ContentType column \-------------------------------------------------------------------------------------------------------------------------*/ - Columns.Add(new DataColumn() { + Columns.Add(new() { DataType = typeof(string), ColumnName = "ContentType" }); @@ -57,7 +57,7 @@ public TopicsDataTable() : base("Topics") { /*-------------------------------------------------------------------------------------------------------------------------- | Add ParentId column \-------------------------------------------------------------------------------------------------------------------------*/ - Columns.Add(new DataColumn() { + Columns.Add(new() { DataType = typeof(int), ColumnName = "ParentId", AllowDBNull = true @@ -66,7 +66,7 @@ public TopicsDataTable() : base("Topics") { /*-------------------------------------------------------------------------------------------------------------------------- | Add HasChildren column \-------------------------------------------------------------------------------------------------------------------------*/ - Columns.Add(new DataColumn() { + Columns.Add(new() { DataType = typeof(bool), ColumnName = "HasChildren", AllowDBNull = true @@ -75,7 +75,7 @@ public TopicsDataTable() : base("Topics") { /*-------------------------------------------------------------------------------------------------------------------------- | Add HasExtendedAttributes column \-------------------------------------------------------------------------------------------------------------------------*/ - Columns.Add(new DataColumn() { + Columns.Add(new() { DataType = typeof(bool), ColumnName = "HasExtendedAttributes", AllowDBNull = true diff --git a/OnTopic.Tests/Schemas/VersionHistoryDataTable.cs b/OnTopic.Tests/Schemas/VersionHistoryDataTable.cs index 4973d3c4..50ffac5a 100644 --- a/OnTopic.Tests/Schemas/VersionHistoryDataTable.cs +++ b/OnTopic.Tests/Schemas/VersionHistoryDataTable.cs @@ -33,7 +33,7 @@ public VersionHistoryDataTable() : base("VersionHistory") { /*-------------------------------------------------------------------------------------------------------------------------- | Add TopicId column \-------------------------------------------------------------------------------------------------------------------------*/ - Columns.Add(new DataColumn() { + Columns.Add(new() { DataType = typeof(int), ColumnName = "TopicId", Unique = true @@ -42,7 +42,7 @@ public VersionHistoryDataTable() : base("VersionHistory") { /*-------------------------------------------------------------------------------------------------------------------------- | Add Version column \-------------------------------------------------------------------------------------------------------------------------*/ - Columns.Add(new DataColumn() { + Columns.Add(new() { DataType = typeof(DateTime), ColumnName = "Version" }); diff --git a/OnTopic.Tests/TopicRepositoryBaseTest.cs b/OnTopic.Tests/TopicRepositoryBaseTest.cs index 0bbc93ea..d48048bc 100644 --- a/OnTopic.Tests/TopicRepositoryBaseTest.cs +++ b/OnTopic.Tests/TopicRepositoryBaseTest.cs @@ -185,7 +185,7 @@ await Assert.ThrowsAsync(() => [Fact] public async Task Load_OldDate_ThrowsException() => await Assert.ThrowsAsync(() => - _cachedTopicRepository.Load(1111, new DateTime(2010, 10, 15)) + _cachedTopicRepository.Load(1111, new(2010, 10, 15)) ); /*============================================================================================================================ From 7bf98af291ffa213bab957e7605d887027d0e073 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Wed, 8 Jul 2026 23:36:42 -0700 Subject: [PATCH 117/337] Ensure assignments are aligned at Character 33 --- OnTopic.AspNetCore.Mvc.Host/Program.cs | 6 +- .../Repositories/StubTopicRepository.cs | 8 +- .../SampleActivator.cs | 18 +-- .../Startup.cs | 4 +- .../ServiceCollectionExtensionsTests.cs | 2 +- .../TopicViewLocationExpanderTest.cs | 10 +- .../TopicViewResultExecutorTest.cs | 8 +- .../TestDoubles/TestTopicRepository.cs | 2 +- .../TopicRepositoryExtensionsTest.cs | 2 +- .../TopicViewComponentTest.cs | 12 +- .../ValidateTopicAttributeTest.cs | 18 +-- .../Components/MenuViewComponentBase{T}.cs | 12 +- .../NavigationTopicViewComponentBase{T}.cs | 4 +- ...PageLevelNavigationViewComponentBase{T}.cs | 10 +- .../Controllers/SitemapController.cs | 12 +- .../Controllers/TopicController.cs | 6 +- .../ServiceCollectionExtensions.cs | 12 +- .../TopicRepositoryExtensions.cs | 6 +- OnTopic.AspNetCore.Mvc/TopicViewResult.cs | 2 +- .../TopicViewResultExecutor.cs | 34 +++--- .../_filters/ValidateTopicAttribute.cs | 16 +-- OnTopic.Data.Caching/CachedTopicRepository.cs | 12 +- OnTopic.Data.Sql/SqlCommandExtensions.cs | 2 +- OnTopic.Data.Sql/SqlDataReaderExtensions.cs | 4 +- OnTopic.Data.Sql/SqlTopicRepository.cs | 8 +- .../Metadata/BooleanAttributeDescriptor.cs | 2 +- .../NestedTopicListAttributeDescriptor.cs | 4 +- .../RelationshipAttributeDescriptor.cs | 4 +- .../Metadata/TextAttributeDescriptor.cs | 4 +- .../TopicReferenceAttributeDescriptor.cs | 4 +- OnTopic.TestDoubles/StubTopicRepository.cs | 46 ++++---- OnTopic.Tests/AttributeCollectionTest.cs | 110 +++++++++--------- .../BindingModels/BasicTopicBindingModel.cs | 4 +- OnTopic.Tests/ContentTypeDescriptorTest.cs | 16 +-- OnTopic.Tests/ContractTest.cs | 6 +- OnTopic.Tests/ITopicRepositoryTest.cs | 2 +- OnTopic.Tests/KeyedTopicCollectionTest.cs | 22 ++-- .../ReverseTopicMappingServiceTest.cs | 10 +- OnTopic.Tests/Schemas/AttributesDataTable.cs | 2 +- .../Schemas/ExtendedAttributesDataTable.cs | 2 +- .../Schemas/RelationshipsDataTable.cs | 2 +- .../Schemas/TopicReferencesDataTable.cs | 2 +- OnTopic.Tests/Schemas/TopicsDataTable.cs | 2 +- .../Schemas/VersionHistoryDataTable.cs | 2 +- OnTopic.Tests/SqlTopicRepositoryTest.cs | 2 +- .../DummyStaticTypeLookupService.cs | 2 +- OnTopic.Tests/TopicMappingServiceTest.cs | 50 ++++---- OnTopic.Tests/TopicQueryingTest.cs | 26 ++--- .../TopicRelationshipMultiMapTest.cs | 12 +- OnTopic.Tests/TopicRepositoryBaseTest.cs | 6 +- OnTopic.Tests/TopicTest.cs | 8 +- OnTopic.Tests/TypeAccessorTest.cs | 2 +- ...buteDictionaryConstructorTopicViewModel.cs | 2 +- .../ViewModels/LoadTestingViewModel.cs | 42 +++---- .../Associations/TopicReferenceCollection.cs | 4 +- .../Associations/TopicRelationshipMultiMap.cs | 4 +- OnTopic/Attributes/AttributeCollection.cs | 10 +- OnTopic/Attributes/AttributeRecord.cs | 2 +- OnTopic/Attributes/AttributeValueConverter.cs | 16 +-- .../ReadOnlyKeyedTopicCollection{T}.cs | 2 +- .../Specialized/ReadOnlyTopicMultiMap.cs | 2 +- ...cordCollection{TItem,TValue,TAttribute}.cs | 38 +++--- OnTopic/Internal/Diagnostics/Contract.cs | 12 +- OnTopic/Internal/Reflection/ItemMetadata.cs | 4 +- OnTopic/Internal/Reflection/MemberAccessor.cs | 6 +- ...Dispatcher{TItem,TValue,TAttributeType}.cs | 8 +- OnTopic/Internal/Reflection/TypeAccessor.cs | 12 +- OnTopic/Lookup/CompositeTypeLookupService.cs | 4 +- OnTopic/Lookup/DynamicTypeLookupService.cs | 2 +- OnTopic/Lookup/StaticTypeLookupService.cs | 2 +- .../Mapping/Annotations/AssociationTypes.cs | 2 +- .../Annotations/AttributeKeyAttribute.cs | 2 +- .../Annotations/CollectionAttribute.cs | 4 +- .../Annotations/FilterByAttributeAttribute.cs | 4 +- .../Annotations/FilterByContentType.cs | 2 +- .../Mapping/Annotations/IncludeAttribute.cs | 2 +- OnTopic/Mapping/Annotations/MapAsAttribute.cs | 2 +- .../Annotations/MapToParentAttribute.cs | 2 +- .../Mapping/Annotations/MetadataAttribute.cs | 2 +- OnTopic/Mapping/CachedTopicMappingService.cs | 14 +-- ...achedHierarchicalTopicMappingService{T}.cs | 6 +- .../HierarchicalTopicMappingService{T}.cs | 18 +-- .../IHierarchicalTopicMappingService{T}.cs | 4 +- OnTopic/Mapping/Internal/AssociationMap.cs | 2 +- OnTopic/Mapping/Internal/ItemConfiguration.cs | 10 +- OnTopic/Mapping/Internal/MappedTopicCache.cs | 12 +- .../Mapping/Reverse/BindingModelValidator.cs | 4 +- .../Reverse/ReverseTopicMappingService.cs | 10 +- OnTopic/Mapping/TopicMappingService.cs | 72 ++++++------ OnTopic/Metadata/AttributeDescriptor.cs | 4 +- OnTopic/Metadata/ContentTypeDescriptor.cs | 4 +- OnTopic/Obsolete/Attributes/AttributeValue.cs | 4 +- .../Collections/AttributeValueCollection.cs | 10 +- .../Collections/NamedTopicCollection.cs | 2 +- .../Mapping/Annotations/FollowAttribute.cs | 2 +- .../Annotations/RelationshipAttribute.cs | 4 +- .../Attributes/AttributeTypeDescriptor.cs | 2 +- .../Obsolete/Repositories/DeleteEventArgs.cs | 2 +- .../Obsolete/Repositories/MoveEventArgs.cs | 4 +- .../Obsolete/Repositories/RenameEventArgs.cs | 2 +- OnTopic/Querying/TopicExtensions.cs | 14 +-- .../Repositories/ObservableTopicRepository.cs | 20 ++-- OnTopic/Repositories/TopicRepository.cs | 18 +-- .../Repositories/TopicRepositoryDecorator.cs | 12 +- OnTopic/Topic.cs | 24 ++-- 105 files changed, 529 insertions(+), 529 deletions(-) diff --git a/OnTopic.AspNetCore.Mvc.Host/Program.cs b/OnTopic.AspNetCore.Mvc.Host/Program.cs index 15bb5613..b2498e34 100644 --- a/OnTopic.AspNetCore.Mvc.Host/Program.cs +++ b/OnTopic.AspNetCore.Mvc.Host/Program.cs @@ -14,14 +14,14 @@ /*============================================================================================================================== | CONFIGURE SERVICES \-----------------------------------------------------------------------------------------------------------------------------*/ -var builder = WebApplication.CreateBuilder(args); +var builder = WebApplication.CreateBuilder(args); /*------------------------------------------------------------------------------------------------------------------------------ | Configure: Cookie Policy \-----------------------------------------------------------------------------------------------------------------------------*/ builder.Services.Configure(options => { // This lambda determines whether user consent for non-essential cookies is needed for a given request. - options.CheckConsentNeeded = context => true; + options.CheckConsentNeeded = context => true; options.MinimumSameSitePolicy = SameSiteMode.None; }); @@ -53,7 +53,7 @@ /*============================================================================================================================== | CONFIGURE APPLICATION \-----------------------------------------------------------------------------------------------------------------------------*/ -var app = builder.Build(); +var app = builder.Build(); /*------------------------------------------------------------------------------------------------------------------------------ | Configure: Error Pages diff --git a/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/Repositories/StubTopicRepository.cs b/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/Repositories/StubTopicRepository.cs index e15c4aa7..700667e1 100644 --- a/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/Repositories/StubTopicRepository.cs +++ b/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/Repositories/StubTopicRepository.cs @@ -34,7 +34,7 @@ public class StubTopicRepository : TopicRepository, ITopicRepository { /// /// A new instance of the StubTopicRepository. public StubTopicRepository() : base() { - _cache = CreateFakeData(); + _cache = CreateFakeData(); Contract.Assume(_cache); } @@ -52,10 +52,10 @@ public StubTopicRepository() : base() { /*-------------------------------------------------------------------------------------------------------------------------- | Lookup by TopicId \-------------------------------------------------------------------------------------------------------------------------*/ - var topic = (Topic?)_cache; + var topic = (Topic?)_cache; if (topicId > 0) { - topic = _cache.FindFirst(t => t.Id.Equals(topicId)); + topic = _cache.FindFirst(t => t.Id.Equals(topicId)); } /*-------------------------------------------------------------------------------------------------------------------------- @@ -90,7 +90,7 @@ public StubTopicRepository() : base() { /*-------------------------------------------------------------------------------------------------------------------------- | Lookup by TopicKey \-------------------------------------------------------------------------------------------------------------------------*/ - var topic = _cache.GetByUniqueKey(uniqueKey); + var topic = _cache.GetByUniqueKey(uniqueKey); /*-------------------------------------------------------------------------------------------------------------------------- | Raise event diff --git a/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/SampleActivator.cs b/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/SampleActivator.cs index ec43e766..1efd6b93 100644 --- a/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/SampleActivator.cs +++ b/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/SampleActivator.cs @@ -57,20 +57,20 @@ public SampleActivator() { \-------------------------------------------------------------------------------------------------------------------------*/ var sqlTopicRepository = new StubTopicRepository(); var cachedTopicRepository = new CachedTopicRepository(sqlTopicRepository); - _ = new PageTopicViewModel(); + _ = new PageTopicViewModel(); /*-------------------------------------------------------------------------------------------------------------------------- | Preload repository \-------------------------------------------------------------------------------------------------------------------------*/ - _topicRepository = cachedTopicRepository; - _typeLookupService = new DynamicTopicViewModelLookupService(); - _topicMappingService = new TopicMappingService(_topicRepository, _typeLookupService); - _ = _topicRepository.Load().GetAwaiter().GetResult(); + _topicRepository = cachedTopicRepository; + _typeLookupService = new DynamicTopicViewModelLookupService(); + _topicMappingService = new TopicMappingService(_topicRepository, _typeLookupService); + _ = _topicRepository.Load().GetAwaiter().GetResult(); /*-------------------------------------------------------------------------------------------------------------------------- | Establish hierarchical topic mapping service \-------------------------------------------------------------------------------------------------------------------------*/ - _hierarchicalMappingService = new CachedHierarchicalTopicMappingService( + _hierarchicalMappingService = new CachedHierarchicalTopicMappingService( new HierarchicalTopicMappingService( _topicRepository, _topicMappingService @@ -96,7 +96,7 @@ public object Create(ControllerContext context) { /*-------------------------------------------------------------------------------------------------------------------------- | Determine controller type \-------------------------------------------------------------------------------------------------------------------------*/ - var type = context.ActionDescriptor.ControllerTypeInfo.AsType(); + var type = context.ActionDescriptor.ControllerTypeInfo.AsType(); /*-------------------------------------------------------------------------------------------------------------------------- | Configure and return appropriate controller @@ -133,13 +133,13 @@ public object Create(ViewComponentContext context) { /*-------------------------------------------------------------------------------------------------------------------------- | Determine view component type \-------------------------------------------------------------------------------------------------------------------------*/ - var type = context.ViewComponentDescriptor.TypeInfo.AsType(); + var type = context.ViewComponentDescriptor.TypeInfo.AsType(); /*-------------------------------------------------------------------------------------------------------------------------- | Configure and return appropriate view component \-------------------------------------------------------------------------------------------------------------------------*/ return type.Name switch { - _ => throw new InvalidOperationException($"Unknown view component {type.Name}") + _ => throw new InvalidOperationException($"Unknown view component {type.Name}") }; } diff --git a/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/Startup.cs b/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/Startup.cs index ecc309f8..50375a27 100644 --- a/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/Startup.cs +++ b/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/Startup.cs @@ -27,7 +27,7 @@ public class Startup { /// The shared dependency. /// public Startup(IConfiguration configuration) { - Configuration = configuration; + Configuration = configuration; } /*============================================================================================================================ @@ -62,7 +62,7 @@ public void ConfigureServices(IServiceCollection services) { /*-------------------------------------------------------------------------------------------------------------------------- | Register: Activators \-------------------------------------------------------------------------------------------------------------------------*/ - var activator = new SampleActivator(); + var activator = new SampleActivator(); services.AddSingleton(activator); services.AddSingleton(activator); diff --git a/OnTopic.AspNetCore.Mvc.IntegrationTests/ServiceCollectionExtensionsTests.cs b/OnTopic.AspNetCore.Mvc.IntegrationTests/ServiceCollectionExtensionsTests.cs index 04f3da61..7ad5bf2a 100644 --- a/OnTopic.AspNetCore.Mvc.IntegrationTests/ServiceCollectionExtensionsTests.cs +++ b/OnTopic.AspNetCore.Mvc.IntegrationTests/ServiceCollectionExtensionsTests.cs @@ -31,7 +31,7 @@ public class ServiceCollectionExtensionsTests: IClassFixture. /// public ServiceCollectionExtensionsTests(WebApplicationFactory factory) { - _factory = factory; + _factory = factory; } /*============================================================================================================================ diff --git a/OnTopic.AspNetCore.Mvc.IntegrationTests/TopicViewLocationExpanderTest.cs b/OnTopic.AspNetCore.Mvc.IntegrationTests/TopicViewLocationExpanderTest.cs index 3328dabe..a21fff40 100644 --- a/OnTopic.AspNetCore.Mvc.IntegrationTests/TopicViewLocationExpanderTest.cs +++ b/OnTopic.AspNetCore.Mvc.IntegrationTests/TopicViewLocationExpanderTest.cs @@ -30,7 +30,7 @@ public class TopicViewLocationExpanderTest: IClassFixture. /// public TopicViewLocationExpanderTest(WebApplicationFactory factory) { - _factory = factory; + _factory = factory; } /*============================================================================================================================ @@ -56,10 +56,10 @@ public TopicViewLocationExpanderTest(WebApplicationFactory factory) { public async Task ExpandViewLocations_Views(string viewName, string viewLocation) { if (viewName is not null && viewName.StartsWith("Area", StringComparison.OrdinalIgnoreCase)) { - viewLocation = $"~/Areas/Area/Views/{viewLocation}"; + viewLocation = $"~/Areas/Area/Views/{viewLocation}"; } else { - viewLocation = $"~/Views/{viewLocation}"; + viewLocation = $"~/Views/{viewLocation}"; } var client = _factory.CreateClient(); @@ -94,10 +94,10 @@ public async Task ExpandViewLocations_Views(string viewName, string viewLocation public async Task ExpandViewLocations_Actions(string viewName, string viewLocation) { if (viewName is not null && viewName.StartsWith("Area", StringComparison.OrdinalIgnoreCase)) { - viewLocation = $"~/Areas/Area/Views/{viewLocation}"; + viewLocation = $"~/Areas/Area/Views/{viewLocation}"; } else { - viewLocation = $"~/Views/{viewLocation}"; + viewLocation = $"~/Views/{viewLocation}"; } var client = _factory.CreateClient(); diff --git a/OnTopic.AspNetCore.Mvc.IntegrationTests/TopicViewResultExecutorTest.cs b/OnTopic.AspNetCore.Mvc.IntegrationTests/TopicViewResultExecutorTest.cs index 439c4c1a..f2294b0b 100644 --- a/OnTopic.AspNetCore.Mvc.IntegrationTests/TopicViewResultExecutorTest.cs +++ b/OnTopic.AspNetCore.Mvc.IntegrationTests/TopicViewResultExecutorTest.cs @@ -30,7 +30,7 @@ public class TopicViewResultExecutorTest: IClassFixture. /// public TopicViewResultExecutorTest(WebApplicationFactory factory) { - _factory = factory; + _factory = factory; } /*============================================================================================================================ @@ -154,9 +154,9 @@ public async Task ContentType_ReturnsExpectedView() { [Fact] public async Task MissingView_ReturnsInternalServerError() { - var client = _factory.CreateClient(); - var uri = new Uri("/Web/MissingView/", UriKind.Relative); - var response = await client.GetAsync(uri, TestContext.Current.CancellationToken); + var client = _factory.CreateClient(); + var uri = new Uri("/Web/MissingView/", UriKind.Relative); + var response = await client.GetAsync(uri, TestContext.Current.CancellationToken); Assert.Equal(HttpStatusCode.InternalServerError, response.StatusCode); diff --git a/OnTopic.AspNetCore.Mvc.Tests/TestDoubles/TestTopicRepository.cs b/OnTopic.AspNetCore.Mvc.Tests/TestDoubles/TestTopicRepository.cs index 17937b95..ed4038bb 100644 --- a/OnTopic.AspNetCore.Mvc.Tests/TestDoubles/TestTopicRepository.cs +++ b/OnTopic.AspNetCore.Mvc.Tests/TestDoubles/TestTopicRepository.cs @@ -35,7 +35,7 @@ public class TestTopicRepository: DummyTopicRepository { /// /// A new instance of the StubTopicRepository. public TestTopicRepository() : base() { - _cache = CreateFakeData(); + _cache = CreateFakeData(); Contract.Assume(_cache); } diff --git a/OnTopic.AspNetCore.Mvc.Tests/TopicRepositoryExtensionsTest.cs b/OnTopic.AspNetCore.Mvc.Tests/TopicRepositoryExtensionsTest.cs index 74109b0c..e4295339 100644 --- a/OnTopic.AspNetCore.Mvc.Tests/TopicRepositoryExtensionsTest.cs +++ b/OnTopic.AspNetCore.Mvc.Tests/TopicRepositoryExtensionsTest.cs @@ -38,7 +38,7 @@ public class TopicRepositoryExtensionsTest: IClassFixture { /// crawling the object graph. /// public TopicRepositoryExtensionsTest(StubTopicRepository topicRepository) { - _topicRepository = new CachedTopicRepository(topicRepository); + _topicRepository = new CachedTopicRepository(topicRepository); } /*============================================================================================================================ diff --git a/OnTopic.AspNetCore.Mvc.Tests/TopicViewComponentTest.cs b/OnTopic.AspNetCore.Mvc.Tests/TopicViewComponentTest.cs index 55aca248..208d1cc0 100644 --- a/OnTopic.AspNetCore.Mvc.Tests/TopicViewComponentTest.cs +++ b/OnTopic.AspNetCore.Mvc.Tests/TopicViewComponentTest.cs @@ -241,16 +241,16 @@ public async Task PageLevelNavigation_Invoke_ReturnsNull() { public async Task PageLevelNavigation_InvokeWithNullTopic_ReturnsNull() { - var webPath = "/Invalid/Path/"; + var webPath = "/Invalid/Path/"; - var viewComponent = new PageLevelNavigationViewComponent(_topicRepository, _hierarchicalMappingService) + var viewComponent = new PageLevelNavigationViewComponent(_topicRepository, _hierarchicalMappingService) { - ViewComponentContext = GetViewComponentContext(webPath) + ViewComponentContext = GetViewComponentContext(webPath) }; - var result = await viewComponent.InvokeAsync(); - var concreteResult = result as ViewViewComponentResult; - var model = concreteResult?.ViewData?.Model as NavigationViewModel; + var result = await viewComponent.InvokeAsync(); + var concreteResult = result as ViewViewComponentResult; + var model = concreteResult?.ViewData?.Model as NavigationViewModel; Assert.NotNull(model); Assert.Equal(String.Empty, model?.CurrentWebPath); diff --git a/OnTopic.AspNetCore.Mvc.Tests/ValidateTopicAttributeTest.cs b/OnTopic.AspNetCore.Mvc.Tests/ValidateTopicAttributeTest.cs index 896fa295..bcbfb372 100644 --- a/OnTopic.AspNetCore.Mvc.Tests/ValidateTopicAttributeTest.cs +++ b/OnTopic.AspNetCore.Mvc.Tests/ValidateTopicAttributeTest.cs @@ -34,7 +34,7 @@ public static ActionExecutingContext GetActionExecutingContext(Controller contro var modelState = new ModelStateDictionary(); - var actionContext = new ActionContext( + var actionContext = new ActionContext( new DefaultHttpContext(), new(), new ControllerActionDescriptor(), @@ -62,9 +62,9 @@ public static ActionExecutingContext GetActionExecutingContext(Controller contro public static ControllerContext GetControllerContext() => new( new() { - HttpContext = new DefaultHttpContext(), - RouteData = new(), - ActionDescriptor = new ControllerActionDescriptor() + HttpContext = new DefaultHttpContext(), + RouteData = new(), + ActionDescriptor = new ControllerActionDescriptor() } ); @@ -291,16 +291,16 @@ public void PageGroupTopic_ReturnsRedirect() { [Fact] public void PageGroupTopic_Empty_ReturnsRedirect() { - var validateFilter = new ValidateTopicAttribute(); - var topic = new Topic("Key", "PageGroup"); - var controller = GetTopicController(topic); - var context = GetActionExecutingContext(controller); + var validateFilter = new ValidateTopicAttribute(); + var topic = new Topic("Key", "PageGroup"); + var controller = GetTopicController(topic); + var context = GetActionExecutingContext(controller); validateFilter.OnActionExecuting(context); controller.Dispose(); - var result = context.Result as StatusCodeResult; + var result = context.Result as StatusCodeResult; Assert.NotNull(result); Assert.Equal(403, result?.StatusCode); diff --git a/OnTopic.AspNetCore.Mvc/Components/MenuViewComponentBase{T}.cs b/OnTopic.AspNetCore.Mvc/Components/MenuViewComponentBase{T}.cs index e47c50ea..fe89f0c6 100644 --- a/OnTopic.AspNetCore.Mvc/Components/MenuViewComponentBase{T}.cs +++ b/OnTopic.AspNetCore.Mvc/Components/MenuViewComponentBase{T}.cs @@ -82,9 +82,9 @@ IHierarchicalTopicMappingService hierarchicalTopicMappingService var configuredRoot = CurrentTopic.Attributes.GetValue("NavigationRoot", true); if (!String.IsNullOrEmpty(configuredRoot)) { - navigationRootTopic = TopicRepository.Load("Root:" + configuredRoot, CurrentTopic).GetAwaiter().GetResult(); + navigationRootTopic = TopicRepository.Load("Root:" + configuredRoot, CurrentTopic).GetAwaiter().GetResult(); } - navigationRootTopic ??= HierarchicalTopicMappingService.GetHierarchicalRoot(CurrentTopic, 2, "Web"); + navigationRootTopic ??= HierarchicalTopicMappingService.GetHierarchicalRoot(CurrentTopic, 2, "Web"); /*-------------------------------------------------------------------------------------------------------------------------- | Return root @@ -117,14 +117,14 @@ public async Task InvokeAsync() { /*-------------------------------------------------------------------------------------------------------------------------- | Retrieve root topic \-------------------------------------------------------------------------------------------------------------------------*/ - var navigationRootTopic = GetNavigationRoot(); + var navigationRootTopic = GetNavigationRoot(); /*-------------------------------------------------------------------------------------------------------------------------- | Construct view model \-------------------------------------------------------------------------------------------------------------------------*/ - var navigationViewModel = new NavigationViewModel() { - NavigationRoot = await MapNavigationTopicViewModels(navigationRootTopic).ConfigureAwait(true), - CurrentWebPath = CurrentTopic?.GetWebPath()?? HttpContext.Request.Path + var navigationViewModel = new NavigationViewModel() { + NavigationRoot = await MapNavigationTopicViewModels(navigationRootTopic).ConfigureAwait(true), + CurrentWebPath = CurrentTopic?.GetWebPath()?? HttpContext.Request.Path }; /*-------------------------------------------------------------------------------------------------------------------------- diff --git a/OnTopic.AspNetCore.Mvc/Components/NavigationTopicViewComponentBase{T}.cs b/OnTopic.AspNetCore.Mvc/Components/NavigationTopicViewComponentBase{T}.cs index 34ccac4f..97c9ef39 100644 --- a/OnTopic.AspNetCore.Mvc/Components/NavigationTopicViewComponentBase{T}.cs +++ b/OnTopic.AspNetCore.Mvc/Components/NavigationTopicViewComponentBase{T}.cs @@ -43,7 +43,7 @@ protected NavigationTopicViewComponentBase( ITopicRepository topicRepository, IHierarchicalTopicMappingService hierarchicalTopicMappingService ) { - TopicRepository = topicRepository; + TopicRepository = topicRepository; HierarchicalTopicMappingService = hierarchicalTopicMappingService; } @@ -81,7 +81,7 @@ IHierarchicalTopicMappingService hierarchicalTopicMappingService /// The Topic associated with the current request. protected Topic? CurrentTopic { get { - field ??= TopicRepository.Load(RouteData); + field ??= TopicRepository.Load(RouteData); return field; } } diff --git a/OnTopic.AspNetCore.Mvc/Components/PageLevelNavigationViewComponentBase{T}.cs b/OnTopic.AspNetCore.Mvc/Components/PageLevelNavigationViewComponentBase{T}.cs index 3a7f11df..d0390e67 100644 --- a/OnTopic.AspNetCore.Mvc/Components/PageLevelNavigationViewComponentBase{T}.cs +++ b/OnTopic.AspNetCore.Mvc/Components/PageLevelNavigationViewComponentBase{T}.cs @@ -85,7 +85,7 @@ IHierarchicalTopicMappingService hierarchicalTopicMappingService while ( navigationRootTopic is not null and not ({ Parent: null } or { ContentType: "PageGroup" }) ) { - navigationRootTopic = navigationRootTopic.Parent; + navigationRootTopic = navigationRootTopic.Parent; } } @@ -117,14 +117,14 @@ public async Task InvokeAsync() { /*-------------------------------------------------------------------------------------------------------------------------- | Retrieve root topic \-------------------------------------------------------------------------------------------------------------------------*/ - var navigationRootTopic = GetNavigationRoot(); + var navigationRootTopic = GetNavigationRoot(); /*-------------------------------------------------------------------------------------------------------------------------- | Construct view model \-------------------------------------------------------------------------------------------------------------------------*/ - var navigationViewModel = new NavigationViewModel() { - NavigationRoot = await MapNavigationTopicViewModels(navigationRootTopic).ConfigureAwait(true), - CurrentWebPath = CurrentTopic?.GetWebPath()?? HttpContext.Request.Path + var navigationViewModel = new NavigationViewModel() { + NavigationRoot = await MapNavigationTopicViewModels(navigationRootTopic).ConfigureAwait(true), + CurrentWebPath = CurrentTopic?.GetWebPath()?? HttpContext.Request.Path }; /*-------------------------------------------------------------------------------------------------------------------------- diff --git a/OnTopic.AspNetCore.Mvc/Controllers/SitemapController.cs b/OnTopic.AspNetCore.Mvc/Controllers/SitemapController.cs index dd92fc36..e3841138 100644 --- a/OnTopic.AspNetCore.Mvc/Controllers/SitemapController.cs +++ b/OnTopic.AspNetCore.Mvc/Controllers/SitemapController.cs @@ -101,7 +101,7 @@ public ActionResult Index(bool indent = false, bool includeMetadata = false) { /*-------------------------------------------------------------------------------------------------------------------------- | Ensure topics are loaded \-------------------------------------------------------------------------------------------------------------------------*/ - var rootTopic = _topicRepository.Load().GetAwaiter().GetResult(); + var rootTopic = _topicRepository.Load().GetAwaiter().GetResult(); Contract.Assume( rootTopic, @@ -168,7 +168,7 @@ private List AddTopic(Topic topic, bool includeMetadata = false) { /*-------------------------------------------------------------------------------------------------------------------------- | Establish return collection \-------------------------------------------------------------------------------------------------------------------------*/ - List topics = []; + List topics = []; /*-------------------------------------------------------------------------------------------------------------------------- | Validate topic @@ -183,13 +183,13 @@ private List AddTopic(Topic topic, bool includeMetadata = false) { /*-------------------------------------------------------------------------------------------------------------------------- | Establish variables \-------------------------------------------------------------------------------------------------------------------------*/ - var domain = $"{HttpContext.Request.Scheme}://{HttpContext.Request.Host}"; - var lastModified = new DateTime(Math.Max(topic.LastModified.Ticks, new DateTime(2000, 1, 1).Ticks)); + var domain = $"{HttpContext.Request.Scheme}://{HttpContext.Request.Host}"; + var lastModified = new DateTime(Math.Max(topic.LastModified.Ticks, new DateTime(2000, 1, 1).Ticks)); /*-------------------------------------------------------------------------------------------------------------------------- | Establish root element \-------------------------------------------------------------------------------------------------------------------------*/ - var topicElement = new XElement(_sitemapNamespace + "url", + var topicElement = new XElement(_sitemapNamespace + "url", new XElement(_sitemapNamespace + "loc", domain + topic.GetWebPath()), new XElement(_sitemapNamespace + "changefreq", "monthly"), new XElement(_sitemapNamespace + "lastmod", lastModified.ToString("yyyy-MM-dd", CultureInfo.InvariantCulture)), @@ -229,7 +229,7 @@ XElement getAttributes() => new XText(topic.ContentType?? "Page") ), from attribute in topic.Attributes - let attributeValue = topic.Attributes.GetValue(attribute.Key) + let attributeValue = topic.Attributes.GetValue(attribute.Key) where !ExcludedAttributes.Contains(attribute.Key, StringComparer.OrdinalIgnoreCase) where attributeValue?.Length < 256 select new XElement(_pagemapNamespace + "Attribute", diff --git a/OnTopic.AspNetCore.Mvc/Controllers/TopicController.cs b/OnTopic.AspNetCore.Mvc/Controllers/TopicController.cs index c761af9f..a83b6954 100644 --- a/OnTopic.AspNetCore.Mvc/Controllers/TopicController.cs +++ b/OnTopic.AspNetCore.Mvc/Controllers/TopicController.cs @@ -47,10 +47,10 @@ public class TopicController(ITopicRepository topicRepository, ITopicMappingServ /// The Topic associated with the current request. public Topic? CurrentTopic { get { - field ??= TopicRepository.Load(RouteData); + field ??= TopicRepository.Load(RouteData); return field; } - set => field = value; + set => field = value; } /*============================================================================================================================ @@ -67,7 +67,7 @@ public async virtual Task IndexAsync(string path) { /*-------------------------------------------------------------------------------------------------------------------------- | Establish default view model \-------------------------------------------------------------------------------------------------------------------------*/ - var topicViewModel = await _topicMappingService.MapAsync(CurrentTopic).ConfigureAwait(false); + var topicViewModel = await _topicMappingService.MapAsync(CurrentTopic).ConfigureAwait(false); /*-------------------------------------------------------------------------------------------------------------------------- | Validate dependencies diff --git a/OnTopic.AspNetCore.Mvc/ServiceCollectionExtensions.cs b/OnTopic.AspNetCore.Mvc/ServiceCollectionExtensions.cs index bff32352..c31f6613 100644 --- a/OnTopic.AspNetCore.Mvc/ServiceCollectionExtensions.cs +++ b/OnTopic.AspNetCore.Mvc/ServiceCollectionExtensions.cs @@ -75,8 +75,8 @@ public static IMvcBuilder AddTopicSupport(this IMvcBuilder services) { public static IRouteBuilder MapTopicRoute( this IRouteBuilder routes, string rootTopic, - string controller = "Topic", - string action = "Index" + string controller = "Topic", + string action = "Index" ) => routes.MapRoute( name: $"{rootTopic}Topic", @@ -95,8 +95,8 @@ public static IRouteBuilder MapTopicRoute( public static ControllerActionEndpointConventionBuilder MapTopicRoute( this IEndpointRouteBuilder routes, string rootTopic, - string controller = "Topic", - string action = "Index" + string controller = "Topic", + string action = "Index" ) => routes.MapControllerRoute( name: $"{rootTopic}Topic", @@ -120,8 +120,8 @@ public static ControllerActionEndpointConventionBuilder MapTopicRoute( public static ControllerActionEndpointConventionBuilder MapTopicAreaRoute( this IEndpointRouteBuilder routes, string areaName, - string? controller = null, - string action = "Index" + string? controller = null, + string action = "Index" ) => routes.MapAreaControllerRoute( name: $"TopicAreas", diff --git a/OnTopic.AspNetCore.Mvc/TopicRepositoryExtensions.cs b/OnTopic.AspNetCore.Mvc/TopicRepositoryExtensions.cs index fcda1543..ef17fb92 100644 --- a/OnTopic.AspNetCore.Mvc/TopicRepositoryExtensions.cs +++ b/OnTopic.AspNetCore.Mvc/TopicRepositoryExtensions.cs @@ -59,7 +59,7 @@ RouteData routeData | case particular routes aren't present. That said, if they are defined, but should be excluded from a fallback, then | that path does need to be defined—thus e.g. {area}/{controller}/{path}. \-------------------------------------------------------------------------------------------------------------------------*/ - List paths = [ + List paths = [ cleanPath($"{rootTopic}/{path}"), cleanPath($"{area}/{controller}/{action}/{path}"), cleanPath($"{area}/{controller}/{path}"), @@ -70,13 +70,13 @@ RouteData routeData /*-------------------------------------------------------------------------------------------------------------------------- | Load by path \-------------------------------------------------------------------------------------------------------------------------*/ - var topic = (Topic?)null; + var topic = (Topic?)null; foreach (var searchPath in paths) { if (topic is not null) break; if (String.IsNullOrEmpty(searchPath)) continue; try { - topic = topicRepository.Load(searchPath).GetAwaiter().GetResult(); + topic = topicRepository.Load(searchPath).GetAwaiter().GetResult(); } catch (InvalidKeyException) { //As route data comes from user-submitted requests, it's expected that some may contain invalid keys. From this diff --git a/OnTopic.AspNetCore.Mvc/TopicViewResult.cs b/OnTopic.AspNetCore.Mvc/TopicViewResult.cs index 8093cd6d..cd2125da 100644 --- a/OnTopic.AspNetCore.Mvc/TopicViewResult.cs +++ b/OnTopic.AspNetCore.Mvc/TopicViewResult.cs @@ -94,7 +94,7 @@ public override async Task ExecuteResultAsync(ActionContext context) { /*-------------------------------------------------------------------------------------------------------------------------- | Call associated executor \-------------------------------------------------------------------------------------------------------------------------*/ - var executor = context.HttpContext.RequestServices.GetRequiredService>(); + var executor = context.HttpContext.RequestServices.GetRequiredService>(); await executor.ExecuteAsync(context, this).ConfigureAwait(false); } diff --git a/OnTopic.AspNetCore.Mvc/TopicViewResultExecutor.cs b/OnTopic.AspNetCore.Mvc/TopicViewResultExecutor.cs index c0006f73..f087af3e 100644 --- a/OnTopic.AspNetCore.Mvc/TopicViewResultExecutor.cs +++ b/OnTopic.AspNetCore.Mvc/TopicViewResultExecutor.cs @@ -95,10 +95,10 @@ public ViewEngineResult FindView(ActionContext actionContext, TopicViewResult vi | Determines if the view is defined in the querystring. \-------------------------------------------------------------------------------------------------------------------------*/ if (requestContext.Query.ContainsKey("View")) { - var queryStringValue = requestContext.Query["View"].First(); + var queryStringValue = requestContext.Query["View"].First(); if (queryStringValue is not null) { - view = viewEngine.FindView(actionContext, queryStringValue, isMainPage: true); - searchedPaths = [.. searchedPaths.Union(view.SearchedLocations ?? [])]; + view = viewEngine.FindView(actionContext, queryStringValue, isMainPage: true); + searchedPaths = [.. searchedPaths.Union(view.SearchedLocations ?? [])]; } } @@ -110,16 +110,16 @@ public ViewEngineResult FindView(ActionContext actionContext, TopicViewResult vi if (header is null) { continue; } - var value = header.Replace("+", "-", StringComparison.Ordinal); + var value = header.Replace("+", "-", StringComparison.Ordinal); if (value.Contains('/', StringComparison.Ordinal)) { - value = value[(value.IndexOf('/', StringComparison.Ordinal)+1)..]; + value = value[(value.IndexOf('/', StringComparison.Ordinal)+1)..]; } if (value.Contains(';', StringComparison.Ordinal)) { - value = value[..(value.IndexOf(';', StringComparison.Ordinal))]; + value = value[..(value.IndexOf(';', StringComparison.Ordinal))]; } if (value is not null) { - view = viewEngine.FindView(actionContext, value, isMainPage: true); - searchedPaths = [.. searchedPaths.Union(view.SearchedLocations ?? [])]; + view = viewEngine.FindView(actionContext, value, isMainPage: true); + searchedPaths = [.. searchedPaths.Union(view.SearchedLocations ?? [])]; } if (view?.Success ?? false) { break; @@ -137,10 +137,10 @@ public ViewEngineResult FindView(ActionContext actionContext, TopicViewResult vi \-------------------------------------------------------------------------------------------------------------------------*/ if (!view?.Success ?? true) { if (routeData.Values.TryGetValue("action", out var action)) { - var actionName = action?.ToString()?.Replace("Async", "", StringComparison.OrdinalIgnoreCase); + var actionName = action?.ToString()?.Replace("Async", "", StringComparison.OrdinalIgnoreCase); if (actionName is not null) { - view = ViewEngine.FindView(actionContext, actionName, isMainPage: true); - searchedPaths = [.. searchedPaths.Union(view.SearchedLocations ?? [])]; + view = ViewEngine.FindView(actionContext, actionName, isMainPage: true); + searchedPaths = [.. searchedPaths.Union(view.SearchedLocations ?? [])]; } } } @@ -152,16 +152,16 @@ public ViewEngineResult FindView(ActionContext actionContext, TopicViewResult vi | as it is set as the default View value for the Topic \-------------------------------------------------------------------------------------------------------------------------*/ if (!(view?.Success ?? false) && !String.IsNullOrEmpty(topicView)) { - view = viewEngine.FindView(actionContext, topicView, isMainPage: true); - searchedPaths = [.. searchedPaths.Union(view.SearchedLocations ?? [])]; + view = viewEngine.FindView(actionContext, topicView, isMainPage: true); + searchedPaths = [.. searchedPaths.Union(view.SearchedLocations ?? [])]; } /*-------------------------------------------------------------------------------------------------------------------------- | Default to content type \-------------------------------------------------------------------------------------------------------------------------*/ if (!view?.Success ?? true) { - view = viewEngine.FindView(actionContext, contentType, isMainPage: true); - searchedPaths = [.. searchedPaths.Union(view.SearchedLocations ?? [])]; + view = viewEngine.FindView(actionContext, contentType, isMainPage: true); + searchedPaths = [.. searchedPaths.Union(view.SearchedLocations ?? [])]; } /*-------------------------------------------------------------------------------------------------------------------------- @@ -189,9 +189,9 @@ public async Task ExecuteAsync(ActionContext context, TopicViewResult result) { /*-------------------------------------------------------------------------------------------------------------------------- | Find view \-------------------------------------------------------------------------------------------------------------------------*/ - var viewEngineResult = FindView(context, result); + var viewEngineResult = FindView(context, result); viewEngineResult.EnsureSuccessful(originalLocations: null); - var view = viewEngineResult.View; + var view = viewEngineResult.View; /*-------------------------------------------------------------------------------------------------------------------------- | Execute diff --git a/OnTopic.AspNetCore.Mvc/_filters/ValidateTopicAttribute.cs b/OnTopic.AspNetCore.Mvc/_filters/ValidateTopicAttribute.cs index dab68480..4856ce39 100644 --- a/OnTopic.AspNetCore.Mvc/_filters/ValidateTopicAttribute.cs +++ b/OnTopic.AspNetCore.Mvc/_filters/ValidateTopicAttribute.cs @@ -75,7 +75,7 @@ public override void OnActionExecuting(ActionExecutingContext context) { if (currentTopic is null) { if (!AllowNull) { - context.Result = controller.NotFound(); + context.Result = controller.NotFound(); } return; } @@ -86,7 +86,7 @@ public override void OnActionExecuting(ActionExecutingContext context) { //### TODO JJC082817: Should allow this to be bypassed for administrators; requires introduction of Role dependency //### e.g., if (!Roles.IsUserInRole(Page?.User?.Identity?.Name ?? "", "Administrators")) {...} if (currentTopic.IsDisabled) { - context.Result = new UnauthorizedResult(); + context.Result = new UnauthorizedResult(); return; } @@ -96,7 +96,7 @@ public override void OnActionExecuting(ActionExecutingContext context) { var redirectUrl = currentTopic.Attributes.GetValue("URL"); if (!String.IsNullOrEmpty(redirectUrl)) { - context.Result = controller.RedirectPermanent(redirectUrl); + context.Result = controller.RedirectPermanent(redirectUrl); return; } @@ -107,7 +107,7 @@ public override void OnActionExecuting(ActionExecutingContext context) { | the request is valid, but forbidden. \-------------------------------------------------------------------------------------------------------------------------*/ if (currentTopic is { ContentType: "List"} or { Parent.ContentType: "List" }) { - context.Result = new StatusCodeResult(403); + context.Result = new StatusCodeResult(403); return; } @@ -118,7 +118,7 @@ public override void OnActionExecuting(ActionExecutingContext context) { | indicate that the request is valid, but forbidden. Unlike nested topics, children of containers are potentially valid. \-------------------------------------------------------------------------------------------------------------------------*/ if (currentTopic.ContentType is "Container") { - context.Result = new StatusCodeResult(403); + context.Result = new StatusCodeResult(403); return; } @@ -129,8 +129,8 @@ public override void OnActionExecuting(ActionExecutingContext context) { | redirected to the first (non-hidden, non-disabled) page in the page group. \-------------------------------------------------------------------------------------------------------------------------*/ if (currentTopic.ContentType is "PageGroup") { - var target = currentTopic.Children.Where(t => t.IsVisible()).FirstOrDefault()?.GetWebPath(); - context.Result = target is null? new StatusCodeResult(403) : controller.Redirect(target); + var target = currentTopic.Children.Where(t => t.IsVisible()).FirstOrDefault()?.GetWebPath(); + context.Result = target is null? new StatusCodeResult(403) : controller.Redirect(target); return; } @@ -142,7 +142,7 @@ public override void OnActionExecuting(ActionExecutingContext context) { | same case as assigned in the topic graph, URLs that vary only by case will be redirected to the expected case. \-------------------------------------------------------------------------------------------------------------------------*/ if (!currentTopic.GetWebPath().Equals(context.HttpContext.Request.Path, StringComparison.Ordinal)) { - context.Result = controller.RedirectPermanent(currentTopic.GetWebPath()); + context.Result = controller.RedirectPermanent(currentTopic.GetWebPath()); return; } diff --git a/OnTopic.Data.Caching/CachedTopicRepository.cs b/OnTopic.Data.Caching/CachedTopicRepository.cs index 20ed7fd8..37b3d09b 100644 --- a/OnTopic.Data.Caching/CachedTopicRepository.cs +++ b/OnTopic.Data.Caching/CachedTopicRepository.cs @@ -178,7 +178,7 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos !uniqueKey.StartsWith(_cache.Key + ":", StringComparison.OrdinalIgnoreCase) && !uniqueKey.Equals(_cache.Key, StringComparison.OrdinalIgnoreCase) ) { - uniqueKey = $"{_cache.Key}:{uniqueKey.TrimStart(':')}"; + uniqueKey = $"{_cache.Key}:{uniqueKey.TrimStart(':')}"; } /*-------------------------------------------------------------------------------------------------------------------------- @@ -202,7 +202,7 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos /*-------------------------------------------------------------------------------------------------------------------------- | On miss: Load with ancestors and merge result into the live graph \-------------------------------------------------------------------------------------------------------------------------*/ - var loaded = await TopicRepository.Load(uniqueKey, referenceTopic: null, isRecursive: false) + var loaded = await TopicRepository.Load(uniqueKey, referenceTopic: null, isRecursive: false) .ConfigureAwait(false); if (loaded is null) { @@ -264,7 +264,7 @@ public virtual async Task EnsureLoaded(Topic topic, TopicPayload payload, Cancel /*-------------------------------------------------------------------------------------------------------------------------- | Filter to pending (i.e., not yet Loaded) payload \-------------------------------------------------------------------------------------------------------------------------*/ - payload = topic.FilterPayload(payload); + payload = topic.FilterPayload(payload); if (payload is TopicPayload.None) { return; @@ -493,8 +493,8 @@ private void IndexTopic(Topic topic) { private void MergeIntoCache(Topic loaded) { // Build the ancestor chain from the leaf up to the root (leaf first) - List chain = []; - for (var node = loaded; node is not null; node = node.Parent) { + List chain = []; + for (var node = loaded; node is not null; node = node.Parent) { chain.Add(node); } @@ -512,7 +512,7 @@ private void MergeIntoCache(Topic loaded) { if (node.Parent is not null) { lock (_syncLock) { if (_topicIdIndex.TryGetValue(node.Parent.Id, out var cacheParent) && cacheParent != node.Parent) { - node.Parent = cacheParent; + node.Parent = cacheParent; } } } diff --git a/OnTopic.Data.Sql/SqlCommandExtensions.cs b/OnTopic.Data.Sql/SqlCommandExtensions.cs index 44265bc1..018cc2b3 100644 --- a/OnTopic.Data.Sql/SqlCommandExtensions.cs +++ b/OnTopic.Data.Sql/SqlCommandExtensions.cs @@ -29,7 +29,7 @@ internal static int GetReturnCode(this SqlCommand command, string sqlParameter = command.Parameters.Contains($"@{sqlParameter}"), $"The call to the {command.CommandText} stored procedure did not return the expected 'ReturnCode' parameter." ); - var returnCode = command.Parameters[$"@{sqlParameter}"].Value?.ToString(); + var returnCode = command.Parameters[$"@{sqlParameter}"].Value?.ToString(); if (Int32.TryParse(returnCode, NumberStyles.Integer, CultureInfo.InvariantCulture, out var returnValue)) { return returnValue; } diff --git a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs index d58cd9eb..6ea24612 100644 --- a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs +++ b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs @@ -235,7 +235,7 @@ private static Topic AddTopic(this IDataReader reader, TopicIndex topics, bool? | Establish topic \-------------------------------------------------------------------------------------------------------------------------*/ if (!topics.TryGetValue(topicId, out var current)) { - current = TopicFactory.Create(key, contentType, topicId); + current = TopicFactory.Create(key, contentType, topicId); topics.Add(current.Id, current); } else { @@ -248,7 +248,7 @@ private static Topic AddTopic(this IDataReader reader, TopicIndex topics, bool? | Assign parent \-------------------------------------------------------------------------------------------------------------------------*/ if (parentId >= 0 && current.Parent?.Id != parentId && topics.TryGetValue(parentId, out var parentTopic)) { - current.Parent = parentTopic; + current.Parent = parentTopic; } /*-------------------------------------------------------------------------------------------------------------------------- diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index da396d79..1fb88a72 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -167,7 +167,7 @@ public SqlTopicRepository(string connectionString) : base() { \-------------------------------------------------------------------------------------------------------------------------*/ if (topic is null) { if (topicId == -1) { - topic = TopicFactory.Create("Root", "Container"); + topic = TopicFactory.Create("Root", "Container"); } else { throw new TopicNotFoundException(topicId); @@ -400,7 +400,7 @@ public virtual async Task EnsureLoaded(Topic topic, TopicPayload payload, Cancel /*-------------------------------------------------------------------------------------------------------------------------- | Filter to pending (not yet Loaded) payload \-------------------------------------------------------------------------------------------------------------------------*/ - payload = topic.FilterPayload(payload); + payload = topic.FilterPayload(payload); if (payload is TopicPayload.None) { return; @@ -570,7 +570,7 @@ bool persistRelationships >------------------------------------------------------------------------------------------------------------------------- | Loop through the content type's supported attributes and add attribute to null attributes if topic does not contain it. \-------------------------------------------------------------------------------------------------------------------------*/ - using var attributeValues = new AttributeValuesDataTable(); + using var attributeValues = new AttributeValuesDataTable(); if (areAttributesDirty) { @@ -655,7 +655,7 @@ bool persistRelationships if (topic.IsNew || isTopicDirty || areAttributesDirty) { await command.ExecuteNonQueryAsync().ConfigureAwait(false); - topic.Id = command.GetReturnCode(); + topic.Id = command.GetReturnCode(); } Contract.Assume( diff --git a/OnTopic.TestDoubles/Metadata/BooleanAttributeDescriptor.cs b/OnTopic.TestDoubles/Metadata/BooleanAttributeDescriptor.cs index dd414dfd..8c5da563 100644 --- a/OnTopic.TestDoubles/Metadata/BooleanAttributeDescriptor.cs +++ b/OnTopic.TestDoubles/Metadata/BooleanAttributeDescriptor.cs @@ -28,7 +28,7 @@ public BooleanAttributeDescriptor( string key, string contentType, Topic parent, - int id = -1 + int id = -1 ) : base( key, contentType, diff --git a/OnTopic.TestDoubles/Metadata/NestedTopicListAttributeDescriptor.cs b/OnTopic.TestDoubles/Metadata/NestedTopicListAttributeDescriptor.cs index 46185fd9..267abf3f 100644 --- a/OnTopic.TestDoubles/Metadata/NestedTopicListAttributeDescriptor.cs +++ b/OnTopic.TestDoubles/Metadata/NestedTopicListAttributeDescriptor.cs @@ -28,7 +28,7 @@ public NestedTopicListAttributeDescriptor( string key, string contentType, Topic parent, - int id = -1 + int id = -1 ) : base( key, contentType, @@ -39,7 +39,7 @@ public NestedTopicListAttributeDescriptor( /*-------------------------------------------------------------------------------------------------------------------------- | Initialize values \-------------------------------------------------------------------------------------------------------------------------*/ - ModelType = ModelType.NestedTopic; + ModelType = ModelType.NestedTopic; } diff --git a/OnTopic.TestDoubles/Metadata/RelationshipAttributeDescriptor.cs b/OnTopic.TestDoubles/Metadata/RelationshipAttributeDescriptor.cs index 8f47bb28..f6712d0b 100644 --- a/OnTopic.TestDoubles/Metadata/RelationshipAttributeDescriptor.cs +++ b/OnTopic.TestDoubles/Metadata/RelationshipAttributeDescriptor.cs @@ -28,7 +28,7 @@ public RelationshipAttributeDescriptor( string key, string contentType, Topic parent, - int id = -1 + int id = -1 ) : base( key, contentType, @@ -39,7 +39,7 @@ public RelationshipAttributeDescriptor( /*-------------------------------------------------------------------------------------------------------------------------- | Initialize values \-------------------------------------------------------------------------------------------------------------------------*/ - ModelType = ModelType.Relationship; + ModelType = ModelType.Relationship; } diff --git a/OnTopic.TestDoubles/Metadata/TextAttributeDescriptor.cs b/OnTopic.TestDoubles/Metadata/TextAttributeDescriptor.cs index d116628e..f2a469cc 100644 --- a/OnTopic.TestDoubles/Metadata/TextAttributeDescriptor.cs +++ b/OnTopic.TestDoubles/Metadata/TextAttributeDescriptor.cs @@ -27,8 +27,8 @@ public class TextAttributeDescriptor : AttributeDescriptor { public TextAttributeDescriptor( string key, string contentType, - Topic? parent = null, - int id = -1 + Topic? parent = null, + int id = -1 ) : base( key, contentType, diff --git a/OnTopic.TestDoubles/Metadata/TopicReferenceAttributeDescriptor.cs b/OnTopic.TestDoubles/Metadata/TopicReferenceAttributeDescriptor.cs index fbab6629..4b404133 100644 --- a/OnTopic.TestDoubles/Metadata/TopicReferenceAttributeDescriptor.cs +++ b/OnTopic.TestDoubles/Metadata/TopicReferenceAttributeDescriptor.cs @@ -28,7 +28,7 @@ public TopicReferenceAttributeDescriptor( string key, string contentType, Topic parent, - int id = -1 + int id = -1 ) : base( key, contentType, @@ -39,7 +39,7 @@ public TopicReferenceAttributeDescriptor( /*-------------------------------------------------------------------------------------------------------------------------- | Initialize values \-------------------------------------------------------------------------------------------------------------------------*/ - ModelType = ModelType.Reference; + ModelType = ModelType.Reference; } diff --git a/OnTopic.TestDoubles/StubTopicRepository.cs b/OnTopic.TestDoubles/StubTopicRepository.cs index 2035f453..5553e51e 100644 --- a/OnTopic.TestDoubles/StubTopicRepository.cs +++ b/OnTopic.TestDoubles/StubTopicRepository.cs @@ -39,7 +39,7 @@ public class StubTopicRepository : TopicRepository, ITopicRepository, ITopicLoad /// /// A new instance of the StubTopicRepository. public StubTopicRepository() : base() { - _cache = CreateFakeData(); + _cache = CreateFakeData(); Contract.Assume(_cache); } @@ -57,10 +57,10 @@ public StubTopicRepository() : base() { /*-------------------------------------------------------------------------------------------------------------------------- | Lookup by TopicId \-------------------------------------------------------------------------------------------------------------------------*/ - var topic = _cache; + var topic = _cache; if (topicId > 0) { - topic = _cache.FindFirst(t => t.Id.Equals(topicId)); + topic = _cache.FindFirst(t => t.Id.Equals(topicId)); } /*-------------------------------------------------------------------------------------------------------------------------- @@ -102,7 +102,7 @@ public StubTopicRepository() : base() { /*-------------------------------------------------------------------------------------------------------------------------- | Lookup by TopicKey \-------------------------------------------------------------------------------------------------------------------------*/ - var topic = _cache.GetByUniqueKey(uniqueKey); + var topic = _cache.GetByUniqueKey(uniqueKey); /*-------------------------------------------------------------------------------------------------------------------------- | Stamp resolver @@ -140,10 +140,10 @@ public StubTopicRepository() : base() { /*-------------------------------------------------------------------------------------------------------------------------- | Lookup by TopicId \-------------------------------------------------------------------------------------------------------------------------*/ - var topic = _cache; + var topic = _cache; if (topicId > 0) { - topic = _cache.FindFirst(t => t.Id.Equals(topicId)); + topic = _cache.FindFirst(t => t.Id.Equals(topicId)); } /*-------------------------------------------------------------------------------------------------------------------------- @@ -167,7 +167,7 @@ public StubTopicRepository() : base() { if (!topic.VersionHistory.Contains(version)) { topic.VersionHistory.Add(version); } - topic.LastModified = version; + topic.LastModified = version; } /*-------------------------------------------------------------------------------------------------------------------------- @@ -193,7 +193,7 @@ protected override Task SaveTopic([NotNull]Topic topic, DateTime version, bool p | Assign faux identity \-------------------------------------------------------------------------------------------------------------------------*/ if (topic.IsNew) { - topic.Id = _identity++; + topic.Id = _identity++; } return Task.CompletedTask; @@ -254,8 +254,8 @@ public virtual Task EnsureLoaded(Topic topic, TopicPayload payload, Cancellation public IEnumerable GetAttributesProxy( Topic topic, bool? isExtendedAttribute, - bool? isDirty = null, - bool excludeLastModified = false + bool? isDirty = null, + bool excludeLastModified = false ) => base.GetAttributes(topic, isExtendedAttribute, isDirty, excludeLastModified); /*============================================================================================================================ @@ -301,21 +301,21 @@ private static Topic CreateFakeData() { /*-------------------------------------------------------------------------------------------------------------------------- | Establish root \-------------------------------------------------------------------------------------------------------------------------*/ - var currentAttributeId = 800; - var rootTopic = new Topic("Root", "Container", null, currentAttributeId++); + var currentAttributeId = 800; + var rootTopic = new Topic("Root", "Container", null, currentAttributeId++); /*-------------------------------------------------------------------------------------------------------------------------- | Establish configuration \-------------------------------------------------------------------------------------------------------------------------*/ - var configuration = new Topic("Configuration", "Container", rootTopic, currentAttributeId++); - var contentTypes = new ContentTypeDescriptor("ContentTypes", "ContentTypeDescriptor", configuration, currentAttributeId++); + var configuration = new Topic("Configuration", "Container", rootTopic, currentAttributeId++); + var contentTypes = new ContentTypeDescriptor("ContentTypes", "ContentTypeDescriptor", configuration, currentAttributeId++); addAttribute(contentTypes, "Key", "TextAttributeDescriptor", false, true); addAttribute(contentTypes, "ContentType", "TextAttributeDescriptor", false, true); addAttribute(contentTypes, "Title", "TextAttributeDescriptor", true, true); addAttribute(contentTypes, "BaseTopic", "TopicReferenceAttributeDescriptor", false); - var contentTypeDescriptor = new ContentTypeDescriptor("ContentTypeDescriptor", "ContentTypeDescriptor", contentTypes, currentAttributeId++); + var contentTypeDescriptor = new ContentTypeDescriptor("ContentTypeDescriptor", "ContentTypeDescriptor", contentTypes, currentAttributeId++); addAttribute(contentTypeDescriptor, "ContentTypes", "RelationshipAttributeDescriptor"); addAttribute(contentTypeDescriptor, "Attributes", "NestedTopicListAttributeDescriptor"); @@ -325,7 +325,7 @@ private static Topic CreateFakeData() { TopicFactory.Create("LookupListItem", "ContentTypeDescriptor", contentTypes); TopicFactory.Create("List", "ContentTypeDescriptor", contentTypes); - var attributeDescriptor = new ContentTypeDescriptor("AttributeDescriptor", "ContentTypeDescriptor", contentTypes, currentAttributeId++); + var attributeDescriptor = new ContentTypeDescriptor("AttributeDescriptor", "ContentTypeDescriptor", contentTypes, currentAttributeId++); addAttribute(attributeDescriptor, "DefaultValue", "TextAttributeDescriptor", false, true); addAttribute(attributeDescriptor, "IsRequired", "TextAttributeDescriptor", false, true); @@ -337,14 +337,14 @@ private static Topic CreateFakeData() { TopicFactory.Create("TextAttributeDescriptor", "ContentTypeDescriptor", attributeDescriptor); TopicFactory.Create("TopicReferenceAttributeDescriptor", "ContentTypeDescriptor", attributeDescriptor); - var pageContentType = new ContentTypeDescriptor("Page", "ContentTypeDescriptor", contentTypes, currentAttributeId++); + var pageContentType = new ContentTypeDescriptor("Page", "ContentTypeDescriptor", contentTypes, currentAttributeId++); addAttribute(pageContentType, "MetaTitle"); addAttribute(pageContentType, "MetaDescription"); addAttribute(pageContentType, "IsHidden", "TextAttributeDescriptor", false); addAttribute(pageContentType, "TopicReference", "TopicReferenceAttributeDescriptor", false); - var contactContentType = new ContentTypeDescriptor("Contact", "ContentTypeDescriptor", contentTypes, currentAttributeId++); + var contactContentType = new ContentTypeDescriptor("Contact", "ContentTypeDescriptor", contentTypes, currentAttributeId++); addAttribute(contactContentType, "Name", isExtended: false); addAttribute(contactContentType, "AlternateEmail", isExtended: false); @@ -382,14 +382,14 @@ AttributeDescriptor addAttribute( var categories = new Topic("Categories", "Lookup", metadata, currentAttributeId++); var lookup = new Topic("LookupList", "List", categories, currentAttributeId++); - for (var i=1; i<=5; i++) { - _ = new Topic("Category" + i, "LookupListItem", lookup); + for (var i =1; i<=5; i++) { + _ = new Topic("Category" + i, "LookupListItem", lookup); } /*-------------------------------------------------------------------------------------------------------------------------- | Establish content \-------------------------------------------------------------------------------------------------------------------------*/ - var web = TopicFactory.Create("Web", "Page", rootTopic, 10000); + var web = TopicFactory.Create("Web", "Page", rootTopic, 10000); CreateFakeData(web, 2, 3); @@ -414,8 +414,8 @@ AttributeDescriptor addAttribute( /// Creates a collection of fake data recursively based on a parent topic, and set number of levels. /// private static void CreateFakeData(Topic parent, int count = 3, int depth = 3) { - for (var i = 0; i < count; i++) { - var topic = new Topic(parent.Key + "_" + i, "Page", parent, parent.Id + (int)Math.Pow(10, depth) * i); + for (var i = 0; i < count; i++) { + var topic = new Topic(parent.Key + "_" + i, "Page", parent, parent.Id + (int)Math.Pow(10, depth) * i); topic.Attributes.SetValue("ParentKey", parent.Key); topic.Attributes.SetValue("DepthCount", (depth+i).ToString(CultureInfo.InvariantCulture)); if (depth > 0) { diff --git a/OnTopic.Tests/AttributeCollectionTest.cs b/OnTopic.Tests/AttributeCollectionTest.cs index b89423b0..8df4c76b 100644 --- a/OnTopic.Tests/AttributeCollectionTest.cs +++ b/OnTopic.Tests/AttributeCollectionTest.cs @@ -67,7 +67,7 @@ public void GetValue_InheritedValue_IsReturned() { [Fact] public void GetValue_MissingValue_ReturnsDefault() { - var topic = new Topic("Test", "Container"); + var topic = new Topic("Test", "Container"); Assert.Null(topic.Attributes.GetValue("InvalidAttribute")); Assert.Equal("Foo", topic.Attributes.GetValue("InvalidAttribute", "Foo")); @@ -84,7 +84,7 @@ public void GetValue_MissingValue_ReturnsDefault() { [Fact] public void GetValue_EmptyValue_ReturnsNull() { - var topic = new Topic("Test", "Container"); + var topic = new Topic("Test", "Container"); topic.Attributes.Add(new("EmptyValue", "")); @@ -101,7 +101,7 @@ public void GetValue_EmptyValue_ReturnsNull() { [Fact] public void GetInteger_CorrectValue_IsReturned() { - var topic = new Topic("Test", "Container"); + var topic = new Topic("Test", "Container"); topic.Attributes.SetInteger("Number1", 1); @@ -142,7 +142,7 @@ public void GetInteger_InheritedValue_IsReturned() { [Fact] public void GetInteger_IncorrectValue_ReturnsDefault() { - var topic = new Topic("Test", "Container"); + var topic = new Topic("Test", "Container"); topic.Attributes.SetValue("Number3", "Invalid"); @@ -160,7 +160,7 @@ public void GetInteger_IncorrectValue_ReturnsDefault() { [Fact] public void GetInteger_IncorrectKey_ReturnsDefault() { - var topic = new Topic("Test", "Container"); + var topic = new Topic("Test", "Container"); Assert.Equal(0, topic.Attributes.GetInteger("InvalidKey")); Assert.Equal(5, topic.Attributes.GetInteger("InvalidKey", 5)); @@ -176,7 +176,7 @@ public void GetInteger_IncorrectKey_ReturnsDefault() { [Fact] public void GetDouble_CorrectValue_IsReturned() { - var topic = new Topic("Test", "Container"); + var topic = new Topic("Test", "Container"); topic.Attributes.SetDouble("Number1", 1); @@ -217,7 +217,7 @@ public void GetDouble_InheritedValue_IsReturned() { [Fact] public void GetDouble_IncorrectValue_ReturnsDefault() { - var topic = new Topic("Test", "Container"); + var topic = new Topic("Test", "Container"); topic.Attributes.SetValue("Number3", "Invalid"); @@ -235,7 +235,7 @@ public void GetDouble_IncorrectValue_ReturnsDefault() { [Fact] public void GetDouble_IncorrectKey_ReturnsDefault() { - var topic = new Topic("Test", "Container"); + var topic = new Topic("Test", "Container"); Assert.Equal(0.0, topic.Attributes.GetDouble("InvalidKey")); Assert.Equal(5.0, topic.Attributes.GetDouble("InvalidKey", 5.0)); @@ -333,7 +333,7 @@ public void GetDateTime_IncorrectKey_ReturnsDefault() { [Fact] public void GetBoolean_CorrectValue_IsReturned() { - var topic = new Topic("Test", "Container"); + var topic = new Topic("Test", "Container"); topic.Attributes.SetBoolean("IsValue1", true); topic.Attributes.SetBoolean("IsValue2", false); @@ -377,7 +377,7 @@ public void GetBoolean_InheritedValue_IsReturned() { [Fact] public void GetBoolean_IncorrectValue_ReturnDefault() { - var topic = new Topic("Test", "Container"); + var topic = new Topic("Test", "Container"); topic.Attributes.SetValue("IsValue", "Invalid"); @@ -396,7 +396,7 @@ public void GetBoolean_IncorrectValue_ReturnDefault() { [Fact] public void GetBoolean_IncorrectKey_ReturnDefault() { - var topic = new Topic("Test", "Container"); + var topic = new Topic("Test", "Container"); Assert.False(topic.Attributes.GetBoolean("InvalidKey")); Assert.True(topic.Attributes.GetBoolean("InvalidKey", true)); @@ -456,7 +456,7 @@ public void GetUri_IncorrectValue_ReturnDefault() { /// [Fact] public void SetValue_CorrectValue_IsReturned() { - var topic = new Topic("Test", "Container"); + var topic = new Topic("Test", "Container"); topic.Attributes.SetValue("Foo", "Bar"); Assert.Equal("Bar", topic.Attributes.GetValue("Foo")); } @@ -470,7 +470,7 @@ public void SetValue_CorrectValue_IsReturned() { [Fact] public void SetValue_ValueChanged_IsDirty() { - var topic = new Topic("Test", "Container"); + var topic = new Topic("Test", "Container"); topic.Attributes.SetValue("Foo", "Bar", false); topic.Attributes.SetValue("Foo", "Baz"); @@ -508,7 +508,7 @@ public void Clear_NonNullableValueWithBusinessLogic_ThrowsException() { [Fact] public void Clear_ExistingValues_IsDirty() { - var topic = new Topic("Test", "Container", null, 1); + var topic = new Topic("Test", "Container", null, 1); topic.Attributes.SetValue("Foo", "Bar", false); @@ -529,7 +529,7 @@ public void Clear_ExistingValues_IsDirty() { [Fact] public void SetValue_ValueUnchanged_IsNotDirty() { - var topic = new Topic("Test", "Container", null, 1); + var topic = new Topic("Test", "Container", null, 1); topic.Attributes.SetValue("Fah", "Bar", false); topic.Attributes.SetValue("Fah", "Bar"); @@ -548,7 +548,7 @@ public void SetValue_ValueUnchanged_IsNotDirty() { [Fact] public void IsDirty_DirtyValues_ReturnsTrue() { - var topic = new Topic("Test", "Container"); + var topic = new Topic("Test", "Container"); topic.Attributes.SetValue("Foo", "Bar"); @@ -568,7 +568,7 @@ public void IsDirty_DirtyValues_ReturnsTrue() { [Fact] public void IsDirty_IsNew_ReturnsTrue() { - var topic = new Topic("Test", "Container"); + var topic = new Topic("Test", "Container"); topic.Attributes.SetValue("Foo", "Bar", false); @@ -590,7 +590,7 @@ public void IsDirty_IsNew_ReturnsTrue() { [Fact] public void IsDirty_DeletedValues_ReturnsTrue() { - var topic = new Topic("Test", "Container", null, 1); + var topic = new Topic("Test", "Container", null, 1); topic.Attributes.SetValue("Foo", "Bar"); topic.Attributes.Remove("Foo"); @@ -610,7 +610,7 @@ public void IsDirty_DeletedValues_ReturnsTrue() { [Fact] public void IsDirty_UndeletedValues_ReturnsFalse() { - var topic = new Topic("Test", "Container", null, 1); + var topic = new Topic("Test", "Container", null, 1); topic.Attributes.SetValue("Foo", "Bar"); topic.Attributes.Remove("Foo"); @@ -633,7 +633,7 @@ public void IsDirty_UndeletedValues_ReturnsFalse() { [Fact] public void IsDirty_NoDirtyValues_ReturnsFalse() { - var topic = new Topic("Test", "Container", null, 1); + var topic = new Topic("Test", "Container", null, 1); topic.Attributes.SetValue("Foo", "Bar", false); @@ -652,7 +652,7 @@ public void IsDirty_NoDirtyValues_ReturnsFalse() { [Fact] public void IsDirty_IsNew_ReturnsFalse() { - var topic = new Topic("Test", "Container"); + var topic = new Topic("Test", "Container"); topic.Attributes.SetValue("Foo", "Bar", false); @@ -670,7 +670,7 @@ public void IsDirty_IsNew_ReturnsFalse() { [Fact] public void IsDirty_MissingKey_ReturnsFalse() { - var topic = new Topic("Test", "Container"); + var topic = new Topic("Test", "Container"); Assert.False(topic.Attributes.IsDirty("MissingKey")); @@ -688,7 +688,7 @@ public void IsDirty_MissingKey_ReturnsFalse() { [Fact] public void IsDirty_ExcludeLastModified_ReturnsFalse() { - var topic = new Topic("Test", "Container", null, 1); + var topic = new Topic("Test", "Container", null, 1); topic.Attributes.SetValue("Foo", "Bar", false); topic.Attributes.SetValue("LastModified", DateTime.Now.ToString(CultureInfo.InvariantCulture)); @@ -743,7 +743,7 @@ public void IsDirty_MarkClean_UpdatesLastModified() { [Fact] public void IsDirty_MarkClean_ReturnsFalse() { - var topic = new Topic("Test", "Container", null, 1); + var topic = new Topic("Test", "Container", null, 1); topic.Attributes.SetValue("Foo", "Bar"); topic.Attributes.SetValue("Baz", "Foo"); @@ -769,7 +769,7 @@ public void IsDirty_MarkClean_ReturnsFalse() { [Fact] public void IsDirty_MarkClean_ReturnsTrue() { - var topic = new Topic("Test", "Container"); + var topic = new Topic("Test", "Container"); topic.Attributes.SetValue("Foo", "Bar"); @@ -790,7 +790,7 @@ public void IsDirty_MarkClean_ReturnsTrue() { [Fact] public void IsDirty_MarkAttributeClean_ReturnsFalse() { - var topic = new Topic("Test", "Container", null, 1); + var topic = new Topic("Test", "Container", null, 1); topic.Attributes.SetValue("Foo", "Bar"); topic.Attributes.MarkClean("Foo"); @@ -810,7 +810,7 @@ public void IsDirty_MarkAttributeClean_ReturnsFalse() { [Fact] public void IsDirty_AddCleanAttributeToNewTopic_ReturnsTrue() { - var topic = new Topic("Test", "Container"); + var topic = new Topic("Test", "Container"); topic.Attributes.Add( new() { @@ -836,7 +836,7 @@ public void IsDirty_AddCleanAttributeToNewTopic_ReturnsTrue() { [Fact] public void IsDirty_MarkNewTopicAsClean_ReturnsTrue() { - var topic = new Topic("Test", "Container"); + var topic = new Topic("Test", "Container"); topic.Attributes.SetValue("Foo", "Bar"); topic.Attributes.MarkClean(); @@ -854,7 +854,7 @@ public void IsDirty_MarkNewTopicAsClean_ReturnsTrue() { [Fact] public void SetValue_InvalidValue_ThrowsException() { - var topic = new Topic("Test", "Container"); + var topic = new Topic("Test", "Container"); Assert.Throws(() => topic.Attributes.SetValue("View", "# ?") @@ -872,7 +872,7 @@ public void SetValue_InvalidValue_ThrowsException() { [Fact] public void SetValue_DuplicateValue_ThrowsException() { - var topic = new Topic("Test", "Container"); + var topic = new Topic("Test", "Container"); topic.Attributes.Add(new("Test", "Original")); @@ -892,7 +892,7 @@ public void SetValue_DuplicateValue_ThrowsException() { [Fact] public void Add_ValidAttributeRecord_IsReturned() { - var topic = new Topic("Test", "Container"); + var topic = new Topic("Test", "Container"); topic.Attributes.Add(new("View", "NewKey", false)); @@ -910,7 +910,7 @@ public void Add_ValidAttributeRecord_IsReturned() { [Fact] public void Add_NumericValueWithBusinessLogic_IsReturned() { - var topic = new CustomTopic("Test", "Page"); + var topic = new CustomTopic("Test", "Page"); topic.Attributes.SetInteger("NumericAttribute", 1); @@ -928,7 +928,7 @@ public void Add_NumericValueWithBusinessLogic_IsReturned() { [Fact] public void Add_BooleanValueWithBusinessLogic_IsReturned() { - var topic = new CustomTopic("Test", "Page"); + var topic = new CustomTopic("Test", "Page"); topic.Attributes.SetBoolean("BooleanAttribute", true); @@ -945,7 +945,7 @@ public void Add_BooleanValueWithBusinessLogic_IsReturned() { [Fact] public void Add_NumericValueWithBusinessLogic_ThrowsException() { - var topic = new CustomTopic("Test", "Page"); + var topic = new CustomTopic("Test", "Page"); Assert.Throws(() => topic.Attributes.SetInteger("NumericAttribute", -1) @@ -963,8 +963,8 @@ public void Add_NumericValueWithBusinessLogic_ThrowsException() { [Fact] public void Add_DateTimeValueWithBusinessLogic_IsReturned() { - var topic = new CustomTopic("Test", "Page"); - var dateTime = new DateTime(2021, 1, 5); + var topic = new CustomTopic("Test", "Page"); + var dateTime = new DateTime(2021, 1, 5); topic.Attributes.SetDateTime("DateTimeAttribute", dateTime); @@ -981,7 +981,7 @@ public void Add_DateTimeValueWithBusinessLogic_IsReturned() { [Fact] public void Add_DateTimeValueWithBusinessLogic_ThrowsException() { - var topic = new CustomTopic("Test", "Page"); + var topic = new CustomTopic("Test", "Page"); Assert.Throws(() => topic.Attributes.SetDateTime("DateTimeAttribute", DateTime.MinValue) @@ -1018,7 +1018,7 @@ public void AttributeRecord_LastModified_DefaultValue() { [Fact] public void Add_InvalidAttributeRecord_ThrowsException() { - var topic = new Topic("Test", "Container"); + var topic = new Topic("Test", "Container"); Assert.Throws(() => topic.Attributes.Add(new("View", "# ?")) @@ -1045,9 +1045,9 @@ public void Add_WithBusinessLogic_MaintainsIsDirty() { Contract.Assume(originalValue); - var index = topic.Attributes.IndexOf(originalValue); + var index = topic.Attributes.IndexOf(originalValue); - topic.Attributes[index] = new AttributeRecord("View", "NewValue", false); + topic.Attributes[index] = new AttributeRecord("View", "NewValue", false); topic.Attributes.TryGetValue("View", out var newAttribute); topic.Attributes.SetValue("View", "NewerValue", false); @@ -1069,7 +1069,7 @@ public void Add_WithBusinessLogic_MaintainsIsDirty() { [Fact] public void SetValue_EmptyAttributeRecord_Skips() { - var topic = new Topic("Test", "Container"); + var topic = new Topic("Test", "Container"); topic.Attributes.SetValue("Attribute", ""); @@ -1088,7 +1088,7 @@ public void SetValue_EmptyAttributeRecord_Skips() { [Fact] public void SetValue_EmptyAttributeRecord_Replaces() { - var topic = new Topic("Test", "Container"); + var topic = new Topic("Test", "Container"); topic.Attributes.SetValue("Attribute", "New Value"); topic.Attributes.SetValue("Attribute", ""); @@ -1106,12 +1106,12 @@ public void SetValue_EmptyAttributeRecord_Replaces() { [Fact] public void GetValue_InheritFromParent_ReturnsParentValue() { - var topics = new Topic[8]; + var topics = new Topic[8]; - for (var i = 0; i <= 7; i++) { - var topic = new Topic("Topic" + i, "Container"); - if (i > 0) topic.Parent = topics[i - 1]; - topics[i] = topic; + for (var i = 0; i <= 7; i++) { + var topic = new Topic("Topic" + i, "Container"); + if (i > 0) topic.Parent = topics[i - 1]; + topics[i] = topic; } topics[0].Attributes.SetValue("Foo", "Bar"); @@ -1131,12 +1131,12 @@ public void GetValue_InheritFromParent_ReturnsParentValue() { [Fact] public void GetValue_InheritFromBase_ReturnsInheritedValue() { - var topics = new Topic[5]; + var topics = new Topic[5]; - for (var i = 0; i <= 4; i++) { - var topic = new Topic("Topic" + i, "Container"); + for (var i = 0; i <= 4; i++) { + var topic = new Topic("Topic" + i, "Container"); if (i > 0) topics[i - 1].BaseTopic = topic; - topics[i] = topic; + topics[i] = topic; } topics[4].Attributes.SetValue("Foo", "Bar"); @@ -1154,12 +1154,12 @@ public void GetValue_InheritFromBase_ReturnsInheritedValue() { [Fact] public void GetValue_ExceedsMaxHops_ReturnsDefault() { - var topics = new Topic[8]; + var topics = new Topic[8]; - for (var i = 0; i <= 7; i++) { - var topic = new Topic("Topic" + i, "Container"); + for (var i = 0; i <= 7; i++) { + var topic = new Topic("Topic" + i, "Container"); if (i > 0) topics[i - 1].BaseTopic = topic; - topics[i] = topic; + topics[i] = topic; } topics[7].Attributes.SetValue("Foo", "Bar"); diff --git a/OnTopic.Tests/BindingModels/BasicTopicBindingModel.cs b/OnTopic.Tests/BindingModels/BasicTopicBindingModel.cs index 03d94e48..75e1a95c 100644 --- a/OnTopic.Tests/BindingModels/BasicTopicBindingModel.cs +++ b/OnTopic.Tests/BindingModels/BasicTopicBindingModel.cs @@ -22,8 +22,8 @@ public class BasicTopicBindingModel : ITopicBindingModel { public BasicTopicBindingModel() { } public BasicTopicBindingModel(string key, string contentType) { - Key = key; - ContentType = contentType; + Key = key; + ContentType = contentType; } [Required] diff --git a/OnTopic.Tests/ContentTypeDescriptorTest.cs b/OnTopic.Tests/ContentTypeDescriptorTest.cs index 7a803b6a..e44225d8 100644 --- a/OnTopic.Tests/ContentTypeDescriptorTest.cs +++ b/OnTopic.Tests/ContentTypeDescriptorTest.cs @@ -150,9 +150,9 @@ public void ContentTypeDescriptor_ResetAttributeDescriptors_ReturnsUpdated() { [Fact] public void IsTypeOf_DerivedContentType_ReturnsTrue() { - var contentType = new ContentTypeDescriptor("Root", "ContentTypeDescriptor"); - for (var i = 0; i < 5; i++) { - var childContentType = new ContentTypeDescriptor("ContentType" + i, "ContentTypeDescriptor", contentType); + var contentType = new ContentTypeDescriptor("Root", "ContentTypeDescriptor"); + for (var i = 0; i < 5; i++) { + var childContentType = new ContentTypeDescriptor("ContentType" + i, "ContentTypeDescriptor", contentType); contentType = childContentType; } @@ -170,9 +170,9 @@ public void IsTypeOf_DerivedContentType_ReturnsTrue() { [Fact] public void IsTypeOf_InvalidContentType_ReturnsFalse() { - var contentType = new ContentTypeDescriptor("Root", "ContentTypeDescriptor"); - for (var i = 0; i < 5; i++) { - var childContentType = new ContentTypeDescriptor("ContentType" + i, "ContentTypeDescriptor", contentType); + var contentType = new ContentTypeDescriptor("Root", "ContentTypeDescriptor"); + for (var i = 0; i < 5; i++) { + var childContentType = new ContentTypeDescriptor("ContentType" + i, "ContentTypeDescriptor", contentType); contentType = childContentType; } @@ -194,7 +194,7 @@ public void ContentTypeDescriptorCollection_ConstructWithValues_ReturnsValues() var pageContentType = new ContentTypeDescriptor("Page", "ContentTypeDescriptor", rootContentType); _ = new ContentTypeDescriptor("Video", "ContentTypeDescriptor", pageContentType); - var contentTypeCollection = new ContentTypeDescriptorCollection(rootContentType); + var contentTypeCollection = new ContentTypeDescriptorCollection(rootContentType); Assert.Equal(3, contentTypeCollection.Count); @@ -215,7 +215,7 @@ public void ContentTypeDescriptorCollection_Refresh_ReturnsUpdated() { var videoContentType = new ContentTypeDescriptor("Video", "ContentTypeDescriptor", pageContentType); var slideshowContentType = new ContentTypeDescriptor("Slideshow", "ContentTypeDescriptor"); - var contentTypeCollection = new ContentTypeDescriptorCollection(rootContentType); + var contentTypeCollection = new ContentTypeDescriptorCollection(rootContentType); pageContentType.Children.Remove(videoContentType); pageContentType.Children.Add(slideshowContentType); diff --git a/OnTopic.Tests/ContractTest.cs b/OnTopic.Tests/ContractTest.cs index 40e13ed4..6a8c7e81 100644 --- a/OnTopic.Tests/ContractTest.cs +++ b/OnTopic.Tests/ContractTest.cs @@ -73,7 +73,7 @@ public void Requires_ObjectIsNull_ThrowArgumentNullException() => [Fact] public void Requires_MessageExists_ThrowExceptionWithMessage() { - var errorMessage = "The argument cannot be null"; + var errorMessage = "The argument cannot be null"; try { Contract.Requires(false, errorMessage); @@ -94,7 +94,7 @@ public void Requires_MessageExists_ThrowExceptionWithMessage() { /// [Fact] public void Requires_InvalidConstructor_ThrowArgumentException() { - var errorMessage = "The argument cannot be null"; + var errorMessage = "The argument cannot be null"; Assert.Throws(() => Contract.Requires(false, errorMessage) ); @@ -146,7 +146,7 @@ public void Assume_ConditionIsFalse_ThrowCustomExpection() => /// [Fact] public void Assume_ConditionIsFalse_ThrowCustomExpectionWithoutMessage() { - var exception = Assert.Throws(() => + var exception = Assert.Throws(() => Contract.Assume(false) ); Assert.Equal("false", exception.Message); diff --git a/OnTopic.Tests/ITopicRepositoryTest.cs b/OnTopic.Tests/ITopicRepositoryTest.cs index f807c1bf..c643717c 100644 --- a/OnTopic.Tests/ITopicRepositoryTest.cs +++ b/OnTopic.Tests/ITopicRepositoryTest.cs @@ -52,7 +52,7 @@ public ITopicRepositoryTest(TopicInfrastructureFixture fixt /*-------------------------------------------------------------------------------------------------------------------------- | Establish dependencies \-------------------------------------------------------------------------------------------------------------------------*/ - _topicRepository = fixture.CachedTopicRepository; + _topicRepository = fixture.CachedTopicRepository; } diff --git a/OnTopic.Tests/KeyedTopicCollectionTest.cs b/OnTopic.Tests/KeyedTopicCollectionTest.cs index 60f6ee48..11464f07 100644 --- a/OnTopic.Tests/KeyedTopicCollectionTest.cs +++ b/OnTopic.Tests/KeyedTopicCollectionTest.cs @@ -26,9 +26,9 @@ public class KeyedTopicCollectionTest { [Fact] public void SetTopic_Indexer_ReturnsTopic() { - var topics = new KeyedTopicCollection(); + var topics = new KeyedTopicCollection(); - for (var i = 0; i < 10; i++) { + for (var i = 0; i < 10; i++) { topics.Add(new("Topic" + i, "Page")); } @@ -45,13 +45,13 @@ public void SetTopic_Indexer_ReturnsTopic() { [Fact] public void Constructor_IEnumerable_SeedsTopics() { - List topics = []; + List topics = []; - for (var i = 0; i < 10; i++) { + for (var i = 0; i < 10; i++) { topics.Add(new("Topic" + i, "Page")); } - var topicsCollection = new KeyedTopicCollection(topics); + var topicsCollection = new KeyedTopicCollection(topics); Assert.Equal(10, topicsCollection.Count); @@ -153,13 +153,13 @@ public void ReadOnlyKeyedTopicCollection_GetValue_ReturnsNull() => [Fact] public void AsReadOnly_ReturnsReadOnlyKeyedTopicCollection() { - var topics = new KeyedTopicCollection(); + var topics = new KeyedTopicCollection(); - for (var i = 0; i < 10; i++) { + for (var i = 0; i < 10; i++) { topics.Add(new("Topic" + i, "Page")); } - var readOnlyCollection = topics.AsReadOnly(); + var readOnlyCollection = topics.AsReadOnly(); Assert.Equal(10, readOnlyCollection.Count); Assert.Equal("Topic0", readOnlyCollection.First().Key); @@ -175,13 +175,13 @@ public void AsReadOnly_ReturnsReadOnlyKeyedTopicCollection() { [Fact] public void AsReadOnly_ReturnsReadOnlyTopicCollection() { - var topics = new TopicCollection(); + var topics = new TopicCollection(); - for (var i = 0; i < 10; i++) { + for (var i = 0; i < 10; i++) { topics.Add(new("Topic" + i, "Page")); } - var readOnlyCollection = topics.AsReadOnly(); + var readOnlyCollection = topics.AsReadOnly(); Assert.Equal(10, readOnlyCollection.Count); Assert.Equal("Topic0", readOnlyCollection.First().Key); diff --git a/OnTopic.Tests/ReverseTopicMappingServiceTest.cs b/OnTopic.Tests/ReverseTopicMappingServiceTest.cs index 8252d991..cb31a6a0 100644 --- a/OnTopic.Tests/ReverseTopicMappingServiceTest.cs +++ b/OnTopic.Tests/ReverseTopicMappingServiceTest.cs @@ -141,7 +141,7 @@ public async Task Map_Existing_ReturnsUpdatedTopic() { target.Title = "Original Attribute"; target.DefaultValue = "Hello"; target.IsRequired = true; - target.IsExtendedAttribute= false; + target.IsExtendedAttribute = false; target.Attributes.SetValue("Description", "Original Description"); @@ -244,10 +244,10 @@ public async Task Map_Relationships_ReturnsMappedTopic() { topic.Relationships.SetValue("ContentTypes", contentTypes[4]); - for (var i = 0; i < 3; i++) { + for (var i = 0; i < 3; i++) { bindingModel.ContentTypes.Add( new() { - UniqueKey = contentTypes[i].GetUniqueKey() + UniqueKey = contentTypes[i].GetUniqueKey() } ); } @@ -280,7 +280,7 @@ public async Task Map_Relationships_ThrowException() { bindingModel.ContentTypes.Add( new() { - UniqueKey = "Root:Configuration:InvalidKey" + UniqueKey = "Root:Configuration:InvalidKey" } ); @@ -666,7 +666,7 @@ public async Task Map_DisabledProperty_IsNotMapped() { UnmappedAttribute = "Hello World" }; - var target = await _mappingService.MapAsync(bindingModel); + var target = await _mappingService.MapAsync(bindingModel); Assert.Null(target?.Attributes.GetValue("UnmappedAttribute", null)); diff --git a/OnTopic.Tests/Schemas/AttributesDataTable.cs b/OnTopic.Tests/Schemas/AttributesDataTable.cs index 05e7f2b5..0da03b99 100644 --- a/OnTopic.Tests/Schemas/AttributesDataTable.cs +++ b/OnTopic.Tests/Schemas/AttributesDataTable.cs @@ -82,7 +82,7 @@ public void AddRow(int topicId, string attributeKey, string? attributeValue, Dat /*-------------------------------------------------------------------------------------------------------------------------- | Create new row \-------------------------------------------------------------------------------------------------------------------------*/ - var row = NewRow(); + var row = NewRow(); row["TopicId"] = topicId; row["AttributeKey"] = attributeKey; diff --git a/OnTopic.Tests/Schemas/ExtendedAttributesDataTable.cs b/OnTopic.Tests/Schemas/ExtendedAttributesDataTable.cs index 54e0f131..f30ba40a 100644 --- a/OnTopic.Tests/Schemas/ExtendedAttributesDataTable.cs +++ b/OnTopic.Tests/Schemas/ExtendedAttributesDataTable.cs @@ -74,7 +74,7 @@ public void AddRow(int topicId, XmlDocument xml, DateTime? version = null) { /*-------------------------------------------------------------------------------------------------------------------------- | Create new row \-------------------------------------------------------------------------------------------------------------------------*/ - var row = NewRow(); + var row = NewRow(); row["TopicId"] = topicId; row["AttributesXml"] = xml; diff --git a/OnTopic.Tests/Schemas/RelationshipsDataTable.cs b/OnTopic.Tests/Schemas/RelationshipsDataTable.cs index d3174cf8..3bd93cc4 100644 --- a/OnTopic.Tests/Schemas/RelationshipsDataTable.cs +++ b/OnTopic.Tests/Schemas/RelationshipsDataTable.cs @@ -90,7 +90,7 @@ public void AddRow(int sourceTopicId, string relationshipKey, int targetTopicId, /*-------------------------------------------------------------------------------------------------------------------------- | Create new row \-------------------------------------------------------------------------------------------------------------------------*/ - var row = NewRow(); + var row = NewRow(); row["Source_TopicId"] = sourceTopicId; row["RelationshipKey"] = relationshipKey; diff --git a/OnTopic.Tests/Schemas/TopicReferencesDataTable.cs b/OnTopic.Tests/Schemas/TopicReferencesDataTable.cs index 892300bf..c722b8db 100644 --- a/OnTopic.Tests/Schemas/TopicReferencesDataTable.cs +++ b/OnTopic.Tests/Schemas/TopicReferencesDataTable.cs @@ -82,7 +82,7 @@ public void AddRow(int sourceTopicId, string referenceKey, int? targetTopicId, D /*-------------------------------------------------------------------------------------------------------------------------- | Create new row \-------------------------------------------------------------------------------------------------------------------------*/ - var row = NewRow(); + var row = NewRow(); row["Source_TopicId"] = sourceTopicId; row["ReferenceKey"] = referenceKey; diff --git a/OnTopic.Tests/Schemas/TopicsDataTable.cs b/OnTopic.Tests/Schemas/TopicsDataTable.cs index 92136677..9102674b 100644 --- a/OnTopic.Tests/Schemas/TopicsDataTable.cs +++ b/OnTopic.Tests/Schemas/TopicsDataTable.cs @@ -108,7 +108,7 @@ public void AddRow( /*-------------------------------------------------------------------------------------------------------------------------- | Create new row \-------------------------------------------------------------------------------------------------------------------------*/ - var row = NewRow(); + var row = NewRow(); row["TopicId"] = topicId; row["TopicKey"] = topicKey; diff --git a/OnTopic.Tests/Schemas/VersionHistoryDataTable.cs b/OnTopic.Tests/Schemas/VersionHistoryDataTable.cs index 50ffac5a..14a3666f 100644 --- a/OnTopic.Tests/Schemas/VersionHistoryDataTable.cs +++ b/OnTopic.Tests/Schemas/VersionHistoryDataTable.cs @@ -66,7 +66,7 @@ public void AddRow(int topicId, DateTime version) { /*-------------------------------------------------------------------------------------------------------------------------- | Create new row \-------------------------------------------------------------------------------------------------------------------------*/ - var row = NewRow(); + var row = NewRow(); row["TopicId"] = topicId; row["Version"] = version; diff --git a/OnTopic.Tests/SqlTopicRepositoryTest.cs b/OnTopic.Tests/SqlTopicRepositoryTest.cs index b1cffd01..1ef2018b 100644 --- a/OnTopic.Tests/SqlTopicRepositoryTest.cs +++ b/OnTopic.Tests/SqlTopicRepositoryTest.cs @@ -12,7 +12,7 @@ using OnTopic.Repositories; using OnTopic.Tests.Schemas; using Xunit; -using TopicReferencesDataTable = OnTopic.Tests.Schemas.TopicReferencesDataTable; +using TopicReferencesDataTable = OnTopic.Tests.Schemas.TopicReferencesDataTable; namespace OnTopic.Tests; diff --git a/OnTopic.Tests/TestDoubles/DummyStaticTypeLookupService.cs b/OnTopic.Tests/TestDoubles/DummyStaticTypeLookupService.cs index 1545a1bb..8e954991 100644 --- a/OnTopic.Tests/TestDoubles/DummyStaticTypeLookupService.cs +++ b/OnTopic.Tests/TestDoubles/DummyStaticTypeLookupService.cs @@ -26,7 +26,7 @@ public class DummyStaticTypeLookupService: StaticTypeLookupService { /// /// The list of instances to expose as part of this service. public DummyStaticTypeLookupService( - IEnumerable? types = null + IEnumerable? types = null ): base(types) { } diff --git a/OnTopic.Tests/TopicMappingServiceTest.cs b/OnTopic.Tests/TopicMappingServiceTest.cs index c18b2a78..85fc4208 100644 --- a/OnTopic.Tests/TopicMappingServiceTest.cs +++ b/OnTopic.Tests/TopicMappingServiceTest.cs @@ -98,14 +98,14 @@ public async Task Map_LoadTesting_EvaluateThreshold() { \-------------------------------------------------------------------------------------------------------------------------*/ var topic = new Topic("Test", "ContentList", null); - for (var i = 0; i <= propertyCount; i++) { + for (var i = 0; i <= propertyCount; i++) { topic.Attributes.SetInteger("Property"+i, i); } /*-------------------------------------------------------------------------------------------------------------------------- | Run load testing \-------------------------------------------------------------------------------------------------------------------------*/ - for (var i = 0; i < runs; i++) { + for (var i = 0; i < runs; i++) { await _mappingService.MapAsync(topic); } @@ -186,7 +186,7 @@ public async Task Map_LoadTesting_EvaluateTime() { /*-------------------------------------------------------------------------------------------------------------------------- | Run load testing \-------------------------------------------------------------------------------------------------------------------------*/ - for (var i = 0; i <= runs; i++) { + for (var i = 0; i <= runs; i++) { await _mappingService.MapAsync(topic); } @@ -831,7 +831,7 @@ public async Task Map_AlternateRelationship_ReturnsCorrectRelationship() { ambiguousRelation.Relationships.SetValue("RelationshipAlias", topic); incomingRelation.Relationships.SetValue("AmbiguousRelationship", topic); - var target = await _mappingService.MapAsync(topic); + var target = await _mappingService.MapAsync(topic); Assert.NotNull(target); Assert.Single(target.RelationshipAlias); @@ -977,7 +977,7 @@ public async Task Map_MapToParent_ReturnsMappedModel() { topic.Attributes.SetValue("AncillaryKey", "Ancillary Key"); topic.Attributes.SetValue("AliasedKey", "Aliased Key"); - var target = await _mappingService.MapAsync(topic); + var target = await _mappingService.MapAsync(topic); Assert.Equal("Test", target?.Primary?.Key); Assert.Equal("Aliased Key", target?.Alternate?.Key); @@ -1003,7 +1003,7 @@ public async Task Map_MapAs_ReturnsTopicReference() { topic.References.SetValue("TopicReference", topicReference); - var target = (MapAsTopicViewModel?)await _mappingService.MapAsync(topic); + var target = (MapAsTopicViewModel?)await _mappingService.MapAsync(topic); Assert.NotNull(target?.TopicReference); Assert.IsType(target?.TopicReference); @@ -1028,7 +1028,7 @@ public async Task Map_MapAs_ReturnsRelationships() { topic.Relationships.SetValue("Relationships", relatedTopic); - var target = (MapAsTopicViewModel?)await _mappingService.MapAsync(topic); + var target = (MapAsTopicViewModel?)await _mappingService.MapAsync(topic); Assert.NotNull(target); Assert.Single(target.Relationships); @@ -1347,7 +1347,7 @@ public async Task Map_GetterMethods_MapMethodOutput() { var childTopic = new Topic("Child", "Page", topic); var grandChildTopic = new Topic("GrandChild", "Index", childTopic); - var target = await _mappingService.MapAsync(grandChildTopic); + var target = await _mappingService.MapAsync(grandChildTopic); Assert.Equal("Topic:Child:GrandChild", target?.UniqueKey); @@ -1389,7 +1389,7 @@ public async Task Map_ValidRequiredProperty_IsMapped() { topic.Attributes.SetValue("RequiredAttribute", "Required"); - var target = await _mappingService.MapAsync(topic); + var target = await _mappingService.MapAsync(topic); Assert.Equal("Required", target?.RequiredAttribute); @@ -1515,7 +1515,7 @@ public async Task Map_FilterByAttribute_ReturnsFilteredCollection() { childTopic4.Attributes.SetValue("SomeOtherAttribute", "ValueA"); - var target = await _mappingService.MapAsync(topic); + var target = await _mappingService.MapAsync(topic); Assert.Equal(2, target?.Children.Count); @@ -1556,7 +1556,7 @@ public async Task Map_FilterByContentType_ReturnsFilteredCollection() { var childTopic3 = new Topic("ChildTopic3", "Page", topic); _ = new Topic("ChildTopic4", "Page", childTopic3); - var target = await _mappingService.MapAsync(topic); + var target = await _mappingService.MapAsync(topic); Assert.Equal(2, target?.Children.Count); @@ -1574,14 +1574,14 @@ public async Task Map_FlattenAttribute_ReturnsFlatCollection() { var topic = new Topic("Test", "FlattenChildren"); - for (var i = 0; i < 5; i++) { + for (var i = 0; i < 5; i++) { var childTopic = new Topic("Child" + i, "Page", topic); - for (var j = 0; j < 5; j++) { - _ = new Topic("GrandChild" + i + j, "FlattenChildren", childTopic); + for (var j = 0; j < 5; j++) { + _ = new Topic("GrandChild" + i + j, "FlattenChildren", childTopic); } } - var target = await _mappingService.MapAsync(topic); + var target = await _mappingService.MapAsync(topic); Assert.Equal(25, target?.Children.Count); @@ -1605,7 +1605,7 @@ public async Task Map_FlattenAttribute_ExcludeTopics() { grandChildTopic.IsDisabled = true; - var target = await _mappingService.MapAsync(topic); + var target = await _mappingService.MapAsync(topic); Assert.NotNull(target); Assert.Single(target.Children); @@ -1622,12 +1622,12 @@ public async Task Map_FlattenAttribute_ExcludeTopics() { [Fact] public async Task Map_CachedTopic_ReturnsCachedModel() { - var cachedMappingService = new CachedTopicMappingService(_mappingService); + var cachedMappingService = new CachedTopicMappingService(_mappingService); - var topic = new Topic("Test", "Filtered", null, 5); + var topic = new Topic("Test", "Filtered", null, 5); - var target1 = (FilteredTopicViewModel?)await cachedMappingService.MapAsync(topic); - var target2 = (FilteredTopicViewModel?)await cachedMappingService.MapAsync(topic); + var target1 = (FilteredTopicViewModel?)await cachedMappingService.MapAsync(topic); + var target2 = (FilteredTopicViewModel?)await cachedMappingService.MapAsync(topic); Assert.Equal(target1, target2); @@ -1643,13 +1643,13 @@ public async Task Map_CachedTopic_ReturnsCachedModel() { [Fact] public async Task Map_CachedTopic_ReturnsUniqueReferencePerType() { - var cachedMappingService = new CachedTopicMappingService(_mappingService); + var cachedMappingService = new CachedTopicMappingService(_mappingService); - var topic = new Topic("Test", "Filtered", null, 5); + var topic = new Topic("Test", "Filtered", null, 5); - var target1 = await cachedMappingService.MapAsync(topic); - var target2 = await cachedMappingService.MapAsync(topic); - var target3 = (TopicViewModel?)await cachedMappingService.MapAsync(topic); + var target1 = await cachedMappingService.MapAsync(topic); + var target2 = await cachedMappingService.MapAsync(topic); + var target3 = (TopicViewModel?)await cachedMappingService.MapAsync(topic); Assert.Equal(target1, target2); Assert.NotEqual(target1, target3); diff --git a/OnTopic.Tests/TopicQueryingTest.cs b/OnTopic.Tests/TopicQueryingTest.cs index da8d7bab..88bc09ae 100644 --- a/OnTopic.Tests/TopicQueryingTest.cs +++ b/OnTopic.Tests/TopicQueryingTest.cs @@ -51,7 +51,7 @@ public TopicQueryingTest(TopicInfrastructureFixture fixture /*-------------------------------------------------------------------------------------------------------------------------- | Establish dependencies \-------------------------------------------------------------------------------------------------------------------------*/ - _topicRepository = fixture.CachedTopicRepository; + _topicRepository = fixture.CachedTopicRepository; } @@ -167,7 +167,7 @@ public void GetByUniqueKey_RootKey_ReturnsRootTopic() { var parentTopic = new Topic("ParentTopic", "Page", null, 1); _ = new Topic("ChildTopic", "Page", parentTopic, 2); - var foundTopic = parentTopic.GetByUniqueKey("ParentTopic"); + var foundTopic = parentTopic.GetByUniqueKey("ParentTopic"); Assert.NotNull(foundTopic); Assert.Equal(parentTopic, foundTopic); @@ -186,10 +186,10 @@ public void GetByUniqueKey_ValidKey_ReturnsTopic() { var parentTopic = new Topic("ParentTopic", "Page", null, 1); var childTopic = new Topic("ChildTopic", "Page", parentTopic, 5); var grandChildTopic = new Topic("GrandChildTopic", "Page", childTopic, 20); - var greatGrandChildTopic1 = new Topic("GreatGrandChildTopic1", "Page", grandChildTopic, 7); - var greatGrandChildTopic2 = new Topic("GreatGrandChildTopic2", "Page", grandChildTopic, 7); + var greatGrandChildTopic1 = new Topic("GreatGrandChildTopic1", "Page", grandChildTopic, 7); + var greatGrandChildTopic2 = new Topic("GreatGrandChildTopic2", "Page", grandChildTopic, 7); - var foundTopic = greatGrandChildTopic1.GetByUniqueKey("ParentTopic:ChildTopic:GrandChildTopic:GreatGrandChildTopic2"); + var foundTopic = greatGrandChildTopic1.GetByUniqueKey("ParentTopic:ChildTopic:GrandChildTopic:GreatGrandChildTopic2"); Assert.Equal(greatGrandChildTopic2, foundTopic); @@ -210,7 +210,7 @@ public void GetByUniqueKey_InvalidKey_ReturnsNull() { var grandChildTopic = new Topic("GrandChildTopic", "Page", childTopic, 20); var greatGrandChildTopic = new Topic("GreatGrandChildTopic", "Page", grandChildTopic, 7); - var foundTopic = greatGrandChildTopic.GetByUniqueKey("ParentTopic:ChildTopic:GrandChildTopic:GreatGrandChildTopic2"); + var foundTopic = greatGrandChildTopic.GetByUniqueKey("ParentTopic:ChildTopic:GrandChildTopic:GreatGrandChildTopic2"); Assert.Null(foundTopic); @@ -226,7 +226,7 @@ public void GetByUniqueKey_InvalidKey_ReturnsNull() { public async Task GetContentType_ValidContentType_ReturnsContentType() { var topic = await _topicRepository.Load(11111); - var contentTypeDescriptor = topic?.GetContentTypeDescriptor(); + var contentTypeDescriptor = topic?.GetContentTypeDescriptor(); Assert.NotNull(contentTypeDescriptor); Assert.Equal("Page", contentTypeDescriptor?.Key); @@ -245,7 +245,7 @@ public async Task GetContentType_InvalidContentType_ReturnsNull() { var parentTopic = await _topicRepository.Load(11111); var topic = new Topic("Test", "NonExistent", parentTopic); - var contentTypeDescriptor = topic.GetContentTypeDescriptor(); + var contentTypeDescriptor = topic.GetContentTypeDescriptor(); Assert.Null(contentTypeDescriptor); @@ -270,7 +270,7 @@ public async Task GetContentType_InvalidType_ReturnsNull() { var parentTopic = await _topicRepository.Load(11111); var topic = new Topic("Test", "Title", parentTopic); - var contentTypeDescriptor = topic.GetContentTypeDescriptor(); + var contentTypeDescriptor = topic.GetContentTypeDescriptor(); Assert.Null(contentTypeDescriptor); @@ -289,7 +289,7 @@ public async Task GetContentType_InvalidType_ReturnsNull() { [Fact] public void AnyDirty_DirtyCollection_ReturnTrue() { - var topics = new TopicCollection { + var topics = new TopicCollection { new Topic("Test", "Page") }; @@ -307,7 +307,7 @@ public void AnyDirty_DirtyCollection_ReturnTrue() { [Fact] public void AnyDirty_CleanCollection_ReturnFalse() { - var topics = new TopicCollection { + var topics = new TopicCollection { new Topic("Test", "Page", null, 1) }; @@ -325,7 +325,7 @@ public void AnyDirty_CleanCollection_ReturnFalse() { [Fact] public void AnyNew_ContainsNew_ReturnTrue() { - var topics = new TopicCollection { + var topics = new TopicCollection { new Topic("Test", "Page") }; @@ -343,7 +343,7 @@ public void AnyNew_ContainsNew_ReturnTrue() { [Fact] public void AnyNew_ContainsExisting_ReturnFalse() { - var topics = new TopicCollection { + var topics = new TopicCollection { new Topic("Test", "Page", null, 1) }; diff --git a/OnTopic.Tests/TopicRelationshipMultiMapTest.cs b/OnTopic.Tests/TopicRelationshipMultiMapTest.cs index 48c736af..7af10b9d 100644 --- a/OnTopic.Tests/TopicRelationshipMultiMapTest.cs +++ b/OnTopic.Tests/TopicRelationshipMultiMapTest.cs @@ -187,7 +187,7 @@ public void SetValue_UpdatesKeyCount() { var parent = new Topic("Parent", "Page"); var relationships = new TopicRelationshipMultiMap(parent); - for (var i = 0; i < 5; i++) { + for (var i = 0; i < 5; i++) { relationships.SetValue("Relationship" + i, new Topic("Related" + i, "Page")); } @@ -209,9 +209,9 @@ public void GetEnumerator_ReturnsKeyValuesPairs() { var counter = 0; var multiMap = new TopicMultiMap(); - var readOnlyRelationships = new ReadOnlyTopicMultiMap(multiMap); + var readOnlyRelationships = new ReadOnlyTopicMultiMap(multiMap); - for (var i = 0; i < 5; i++) { + for (var i = 0; i < 5; i++) { multiMap.Add(new("Relationship" + i, new())); } @@ -235,7 +235,7 @@ public void GetEnumerator_ReturnsKeyValuesPairs() { public void Indexer_ReturnsKeyValuesPair() { var multiMap = new TopicMultiMap(); - var readOnlyTopicMultiMap = new ReadOnlyTopicMultiMap(multiMap); + var readOnlyTopicMultiMap = new ReadOnlyTopicMultiMap(multiMap); var topics = new TopicCollection(); var keyValuesPair = new KeyValuesPair("Relationship", topics); var topic = new Topic("Test", "Test"); @@ -261,7 +261,7 @@ public void GetAllValues_ReturnsAllTopics() { var parent = new Topic("Parent", "Page"); var relationships = new TopicRelationshipMultiMap(parent); - for (var i = 0; i < 5; i++) { + for (var i = 0; i < 5; i++) { relationships.SetValue("Relationship" + i, new Topic("Related" + i, "Page")); } @@ -284,7 +284,7 @@ public void GetAllValues_ContentTypes_ReturnsAllContentTypes() { var parent = new Topic("Parent", "Page"); var relationships = new TopicRelationshipMultiMap(parent); - for (var i = 0; i < 5; i++) { + for (var i = 0; i < 5; i++) { relationships.SetValue("Relationship" + i, new Topic("Related" + i, "ContentType" + i)); } diff --git a/OnTopic.Tests/TopicRepositoryBaseTest.cs b/OnTopic.Tests/TopicRepositoryBaseTest.cs index d48048bc..cfd19e27 100644 --- a/OnTopic.Tests/TopicRepositoryBaseTest.cs +++ b/OnTopic.Tests/TopicRepositoryBaseTest.cs @@ -97,7 +97,7 @@ public async Task Load_NegativeTopicId_ReturnsRootTopic() => [Fact] public async Task Load_WithNarrowPayload_ReturnsTopic() { - var topic = await _topicRepository.Load(11111, payload: TopicPayload.None); + var topic = await _topicRepository.Load(11111, payload: TopicPayload.None); Assert.NotNull(topic); @@ -114,7 +114,7 @@ public async Task Load_WithNarrowPayload_ReturnsTopic() { [Fact] public async Task Load_WithNarrowPayload_ExtendedAttributesLoaded() { - var topic = await _topicRepository.Load(11111, payload: TopicPayload.None); + var topic = await _topicRepository.Load(11111, payload: TopicPayload.None); Assert.NotNull(topic); Assert.Equal(LoadState.Loaded, topic.Attributes.LoadState); @@ -918,7 +918,7 @@ public async Task Move_ContentTypeDescriptor_UpdatesContentTypeCache() { var contentTypes = _topicRepository.GetContentTypeDescriptors(); var pageContentType = contentTypes.Contains("Page")? contentTypes["Page"] : null; var contactContentType = contentTypes.Contains("Contact")? contentTypes["Contact"] : null; - var contactAttributeCount = contactContentType?.AttributeDescriptors.Count; + var contactAttributeCount = contactContentType?.AttributeDescriptors.Count; Contract.Assume(contactContentType); Contract.Assume(pageContentType); diff --git a/OnTopic.Tests/TopicTest.cs b/OnTopic.Tests/TopicTest.cs index 5b393d7d..1f4d8cc5 100644 --- a/OnTopic.Tests/TopicTest.cs +++ b/OnTopic.Tests/TopicTest.cs @@ -28,7 +28,7 @@ public class TopicTest { /// [Fact] public void Create_ReturnsTopic() { - var topic = TopicFactory.Create("Test", "Page"); + var topic = TopicFactory.Create("Test", "Page"); Assert.NotNull(topic); Assert.Equal("Test", topic.Key); Assert.Equal("Page", topic.ContentType); @@ -43,7 +43,7 @@ public void Create_ReturnsTopic() { /// [Fact] public void Create_ContentType_ReturnsDerivedTopic() { - var topic = TopicFactory.Create("Test", "ContentTypeDescriptor"); + var topic = TopicFactory.Create("Test", "ContentTypeDescriptor"); Assert.NotNull(topic); Assert.IsType(topic); } @@ -63,7 +63,7 @@ public void Create_ContentType_ReturnsDerivedTopic() { /// [Fact] public void Create_AttributeDescriptor_ReturnsFallback() { - var topic = TopicFactory.Create("Test", "ArbitraryAttributeDescriptor"); + var topic = TopicFactory.Create("Test", "ArbitraryAttributeDescriptor"); Assert.NotNull(topic); Assert.IsType(topic); } @@ -80,7 +80,7 @@ public void Id_ChangeValue_ThrowsArgumentException() { var topic = new ContentTypeDescriptor("Test", "ContentTypeDescriptor", null, 123); Assert.Throws(() => - topic.Id = 124 + topic.Id = 124 ); } diff --git a/OnTopic.Tests/TypeAccessorTest.cs b/OnTopic.Tests/TypeAccessorTest.cs index dd1f3b8c..01d57e62 100644 --- a/OnTopic.Tests/TypeAccessorTest.cs +++ b/OnTopic.Tests/TypeAccessorTest.cs @@ -666,7 +666,7 @@ public void SetPropertyValue_ReflectionPerformance() { var topic = new Topic("Test", "ContentType"); int i; - for (i = 0; i < totalIterations; i++) { + for (i = 0; i < totalIterations; i++) { typeAccessor.SetPropertyValue(topic, "Key", "Key" + i); } diff --git a/OnTopic.Tests/ViewModels/AttributeDictionaryConstructorTopicViewModel.cs b/OnTopic.Tests/ViewModels/AttributeDictionaryConstructorTopicViewModel.cs index 35c1ed3f..942493f2 100644 --- a/OnTopic.Tests/ViewModels/AttributeDictionaryConstructorTopicViewModel.cs +++ b/OnTopic.Tests/ViewModels/AttributeDictionaryConstructorTopicViewModel.cs @@ -27,7 +27,7 @@ public record AttributeDictionaryConstructorTopicViewModel: PageTopicViewModel { /// An of attribute values. public AttributeDictionaryConstructorTopicViewModel(AttributeDictionary attributes) : base(attributes) { Contract.Requires(attributes, nameof(attributes)); - MappedProperty = attributes.GetValue(nameof(MappedProperty)); + MappedProperty = attributes.GetValue(nameof(MappedProperty)); } /// diff --git a/OnTopic.Tests/ViewModels/LoadTestingViewModel.cs b/OnTopic.Tests/ViewModels/LoadTestingViewModel.cs index 2ee9c147..38805228 100644 --- a/OnTopic.Tests/ViewModels/LoadTestingViewModel.cs +++ b/OnTopic.Tests/ViewModels/LoadTestingViewModel.cs @@ -28,27 +28,27 @@ public class LoadTestingViewModel: KeyOnlyTopicViewModel { /// An of attribute values. public LoadTestingViewModel(AttributeDictionary attributes) { Contract.Requires(attributes); - Property0 = attributes.GetInteger("Property0"); - Property1 = attributes.GetInteger("Property1"); - Property2 = attributes.GetInteger("Property2"); - Property3 = attributes.GetInteger("Property3"); - Property4 = attributes.GetInteger("Property4"); - Property5 = attributes.GetInteger("Property5"); - Property6 = attributes.GetInteger("Property6"); - Property7 = attributes.GetInteger("Property7"); - Property8 = attributes.GetInteger("Property8"); - Property9 = attributes.GetInteger("Property9"); - Property10 = attributes.GetInteger("Property10"); - Property11 = attributes.GetInteger("Property11"); - Property12 = attributes.GetInteger("Property12"); - Property13 = attributes.GetInteger("Property13"); - Property14 = attributes.GetInteger("Property14"); - Property15 = attributes.GetInteger("Property15"); - Property16 = attributes.GetInteger("Property16"); - Property17 = attributes.GetInteger("Property17"); - Property18 = attributes.GetInteger("Property18"); - Property19 = attributes.GetInteger("Property19"); - Property20 = attributes.GetInteger("Property20"); + Property0 = attributes.GetInteger("Property0"); + Property1 = attributes.GetInteger("Property1"); + Property2 = attributes.GetInteger("Property2"); + Property3 = attributes.GetInteger("Property3"); + Property4 = attributes.GetInteger("Property4"); + Property5 = attributes.GetInteger("Property5"); + Property6 = attributes.GetInteger("Property6"); + Property7 = attributes.GetInteger("Property7"); + Property8 = attributes.GetInteger("Property8"); + Property9 = attributes.GetInteger("Property9"); + Property10 = attributes.GetInteger("Property10"); + Property11 = attributes.GetInteger("Property11"); + Property12 = attributes.GetInteger("Property12"); + Property13 = attributes.GetInteger("Property13"); + Property14 = attributes.GetInteger("Property14"); + Property15 = attributes.GetInteger("Property15"); + Property16 = attributes.GetInteger("Property16"); + Property17 = attributes.GetInteger("Property17"); + Property18 = attributes.GetInteger("Property18"); + Property19 = attributes.GetInteger("Property19"); + Property20 = attributes.GetInteger("Property20"); } /// diff --git a/OnTopic/Associations/TopicReferenceCollection.cs b/OnTopic/Associations/TopicReferenceCollection.cs index 7ebf3612..d99d3a96 100644 --- a/OnTopic/Associations/TopicReferenceCollection.cs +++ b/OnTopic/Associations/TopicReferenceCollection.cs @@ -89,7 +89,7 @@ protected override void InsertItem(int index, TopicReferenceRecord item) { /*-------------------------------------------------------------------------------------------------------------------------- | Remove any pending deferred entry for this reference key \-------------------------------------------------------------------------------------------------------------------------*/ - for (var i = Deferred.Count - 1; i >= 0; i--) { + for (var i = Deferred.Count - 1; i >= 0; i--) { if (Deferred[i].Key == item.Key) { Deferred.RemoveAt(i); break; @@ -127,7 +127,7 @@ protected override void SetItem(int index, TopicReferenceRecord item) { /*-------------------------------------------------------------------------------------------------------------------------- | Remove any pending deferred entry for this reference key \-------------------------------------------------------------------------------------------------------------------------*/ - for (var i = Deferred.Count - 1; i >= 0; i--) { + for (var i = Deferred.Count - 1; i >= 0; i--) { if (Deferred[i].Key == item.Key) { Deferred.RemoveAt(i); break; diff --git a/OnTopic/Associations/TopicRelationshipMultiMap.cs b/OnTopic/Associations/TopicRelationshipMultiMap.cs index 79bd73d5..34613b41 100644 --- a/OnTopic/Associations/TopicRelationshipMultiMap.cs +++ b/OnTopic/Associations/TopicRelationshipMultiMap.cs @@ -65,7 +65,7 @@ public TopicRelationshipMultiMap(Topic parent, bool isIncoming = false): base(ne public void Clear(string relationshipKey) { Contract.Requires(!String.IsNullOrWhiteSpace(relationshipKey), nameof(relationshipKey)); if (_storage.Contains(relationshipKey)) { - var relationship = _storage.GetValues(relationshipKey); + var relationship = _storage.GetValues(relationshipKey); if (relationship.Count > 0) { _dirtyKeys.MarkAs(relationshipKey, markDirty: !_parent.IsNew); } @@ -213,7 +213,7 @@ internal void SetValue(string relationshipKey, Topic topic, bool? markDirty, boo } // Remove any pending deferred entry for this relationship/target pair - for (var i = Deferred.Count - 1; i >= 0; i--) { + for (var i = Deferred.Count - 1; i >= 0; i--) { if (Deferred[i].Key == relationshipKey && Deferred[i].TopicId == topic.Id) { Deferred.RemoveAt(i); break; diff --git a/OnTopic/Attributes/AttributeCollection.cs b/OnTopic/Attributes/AttributeCollection.cs index d0a04a64..ae8b949e 100644 --- a/OnTopic/Attributes/AttributeCollection.cs +++ b/OnTopic/Attributes/AttributeCollection.cs @@ -166,9 +166,9 @@ public bool IsDirty(bool excludeLastModified) public void SetValue( string key, string? value, - bool? markDirty = null, - DateTime? version = null, - bool? isExtendedAttribute = null + bool? markDirty = null, + DateTime? version = null, + bool? isExtendedAttribute = null ) { base.SetValue(key, value, markDirty, version); if (Contains(key)) { @@ -176,7 +176,7 @@ public void SetValue( var attributeIndex = IndexOf(attributeValue); if (isExtendedAttribute is not null && isExtendedAttribute != attributeValue.IsExtendedAttribute) { attributeValue = attributeValue with { - IsExtendedAttribute = isExtendedAttribute + IsExtendedAttribute = isExtendedAttribute }; base[attributeIndex] = attributeValue; } @@ -210,7 +210,7 @@ public AttributeDictionary AsAttributeDictionary(bool inheritFromBase = false) { attributes.TryAdd(attribute.Key, attribute.Value); } } - sourceAttributes = inheritFromBase? sourceAttributes.AssociatedTopic.BaseTopic?.Attributes : null; + sourceAttributes = inheritFromBase? sourceAttributes.AssociatedTopic.BaseTopic?.Attributes : null; } foreach (var attribute in _excludedAttributes) { attributes.Remove(attribute); diff --git a/OnTopic/Attributes/AttributeRecord.cs b/OnTopic/Attributes/AttributeRecord.cs index d0a26151..9899fa2f 100644 --- a/OnTopic/Attributes/AttributeRecord.cs +++ b/OnTopic/Attributes/AttributeRecord.cs @@ -72,7 +72,7 @@ public AttributeRecord( string? value, bool isDirty = true, DateTime? lastModified = null, - bool? isExtendedAttribute = null + bool? isExtendedAttribute = null ): base(key, value, isDirty, lastModified) { /*-------------------------------------------------------------------------------------------------------------------------- diff --git a/OnTopic/Attributes/AttributeValueConverter.cs b/OnTopic/Attributes/AttributeValueConverter.cs index 934ba78e..781288ab 100644 --- a/OnTopic/Attributes/AttributeValueConverter.cs +++ b/OnTopic/Attributes/AttributeValueConverter.cs @@ -62,7 +62,7 @@ internal static class AttributeValueConverter { /// An instance of the as a . internal static object? Convert(string? value, Type type) { - var valueObject = (object?)null; + var valueObject = (object?)null; //Treat empty as null for non-strings, regardless of whether they’re nullable if (!type.Equals(typeof(string)) && String.IsNullOrWhiteSpace(value)) { @@ -72,34 +72,34 @@ internal static class AttributeValueConverter { if (value is null) return null; if (type.Equals(typeof(string))) { - valueObject = value; + valueObject = value; } else if (type.Equals(typeof(bool)) || type.Equals(typeof(bool?))) { if (value is "1" || value.Equals("true", StringComparison.OrdinalIgnoreCase)) { - valueObject = true; + valueObject = true; } else if (value is "0" || value.Equals("false", StringComparison.OrdinalIgnoreCase)) { - valueObject = false; + valueObject = false; } } else if (type.Equals(typeof(int)) || type.Equals(typeof(int?))) { if (Int32.TryParse(value, out var intValue)) { - valueObject = intValue; + valueObject = intValue; } } else if (type.Equals(typeof(double)) || type.Equals(typeof(double?))) { if (Double.TryParse(value, out var doubleValue)) { - valueObject = doubleValue; + valueObject = doubleValue; } } else if (type.Equals(typeof(DateTime)) || type.Equals(typeof(DateTime?))) { if (DateTime.TryParse(value, out var date)) { - valueObject = date; + valueObject = date; } } else if (type.Equals(typeof(Uri))) { if (Uri.TryCreate(value, UriKind.RelativeOrAbsolute, out var uri)) { - valueObject = uri; + valueObject = uri; } } diff --git a/OnTopic/Collections/ReadOnlyKeyedTopicCollection{T}.cs b/OnTopic/Collections/ReadOnlyKeyedTopicCollection{T}.cs index 891519cd..f0eb8f9d 100644 --- a/OnTopic/Collections/ReadOnlyKeyedTopicCollection{T}.cs +++ b/OnTopic/Collections/ReadOnlyKeyedTopicCollection{T}.cs @@ -28,7 +28,7 @@ public class ReadOnlyKeyedTopicCollection : ReadOnlyCollection where T : T /// /// The underlying . public ReadOnlyKeyedTopicCollection(IList? innerCollection = null) : base(innerCollection ?? []) { - _innerCollection = innerCollection as KeyedTopicCollection?? new(innerCollection); + _innerCollection = innerCollection as KeyedTopicCollection?? new(innerCollection); } /*============================================================================================================================ diff --git a/OnTopic/Collections/Specialized/ReadOnlyTopicMultiMap.cs b/OnTopic/Collections/Specialized/ReadOnlyTopicMultiMap.cs index beb1dd7a..2f89ad0d 100644 --- a/OnTopic/Collections/Specialized/ReadOnlyTopicMultiMap.cs +++ b/OnTopic/Collections/Specialized/ReadOnlyTopicMultiMap.cs @@ -25,7 +25,7 @@ public class ReadOnlyTopicMultiMap: IEnumerable public ReadOnlyTopicMultiMap(TopicMultiMap source) { Contract.Requires(source, nameof(source)); - Source = source; + Source = source; } /*============================================================================================================================ diff --git a/OnTopic/Collections/Specialized/TrackedRecordCollection{TItem,TValue,TAttribute}.cs b/OnTopic/Collections/Specialized/TrackedRecordCollection{TItem,TValue,TAttribute}.cs index 0ab54374..398966ee 100644 --- a/OnTopic/Collections/Specialized/TrackedRecordCollection{TItem,TValue,TAttribute}.cs +++ b/OnTopic/Collections/Specialized/TrackedRecordCollection{TItem,TValue,TAttribute}.cs @@ -250,17 +250,17 @@ public void MarkClean(string key, DateTime? version) { Contract.Requires(maxHops >= 0, "The maximum number of hops should be a positive number."); Contract.Requires(maxHops <= 100, "The maximum number of hops should not exceed 100."); - TValue? value = null; + TValue? value = null; /*-------------------------------------------------------------------------------------------------------------------------- | Look up value from collection \-------------------------------------------------------------------------------------------------------------------------*/ if (Contains(key)) { - value = this[key].Value; + value = this[key].Value; } if (value is "") { - value = null; + value = null; } /*-------------------------------------------------------------------------------------------------------------------------- @@ -271,7 +271,7 @@ value is null && maxHops > 0 && BaseCollection is not null ) { - value = BaseCollection.GetValue(key, null, false, maxHops - 1); + value = BaseCollection.GetValue(key, null, false, maxHops - 1); } /*-------------------------------------------------------------------------------------------------------------------------- @@ -282,7 +282,7 @@ value is null && inheritFromParent && ParentCollection is not null ) { - value = ParentCollection.GetValue(key, defaultValue, inheritFromParent); + value = ParentCollection.GetValue(key, defaultValue, inheritFromParent); } /*-------------------------------------------------------------------------------------------------------------------------- @@ -358,8 +358,8 @@ ParentCollection is not null public virtual void SetValue( string key, TValue? value, - bool? markDirty = null, - DateTime? version = null + bool? markDirty = null, + DateTime? version = null ) => SetValue(key, value, markDirty, true, version); @@ -404,7 +404,7 @@ internal void SetValue( TValue? value, bool? markDirty, bool enforceBusinessLogic, - DateTime? version = null + DateTime? version = null ) { /*-------------------------------------------------------------------------------------------------------------------------- @@ -415,10 +415,10 @@ internal void SetValue( /*-------------------------------------------------------------------------------------------------------------------------- | Retrieve original item \-------------------------------------------------------------------------------------------------------------------------*/ - TItem? originalItem = null; + TItem? originalItem = null; if (Contains(key)) { - originalItem = this[key]; + originalItem = this[key]; } /*-------------------------------------------------------------------------------------------------------------------------- @@ -429,7 +429,7 @@ internal void SetValue( \-------------------------------------------------------------------------------------------------------------------------*/ if (_topicPropertyDispatcher.IsRegistered(key, out var updatedItem)) { if (updatedItem.Value != value) { - updatedItem = updatedItem with { + updatedItem = updatedItem with { Value = value }; } @@ -441,15 +441,15 @@ internal void SetValue( | Because TrackedRecord is immutable, a new instance must be constructed to replace the previous version. \-------------------------------------------------------------------------------------------------------------------------*/ else if (originalItem is not null) { - var markAsDirty = originalItem.IsDirty; + var markAsDirty = originalItem.IsDirty; if (AssociatedTopic.IsNew) { - markAsDirty = true; + markAsDirty = true; } else if (markDirty.HasValue) { - markAsDirty = markDirty.Value; + markAsDirty = markDirty.Value; } else if (!originalItem.Value?.Equals(value)?? false) { - markAsDirty = true; + markAsDirty = true; } else if (!version.HasValue) { return; @@ -476,7 +476,7 @@ internal void SetValue( | Create new item \-------------------------------------------------------------------------------------------------------------------------*/ else { - updatedItem = new TItem() { + updatedItem = new TItem() { Key = key, Value = value, IsDirty = AssociatedTopic.IsNew || (markDirty ?? true), @@ -599,8 +599,8 @@ protected override void SetItem(int index, TItem item) { /// cref="TrackedRecord{T}"/>s are marked as . /// protected override void RemoveItem(int index) { - var trackedRecord = this[index] with { - Value = null + var trackedRecord = this[index] with { + Value = null }; if (_topicPropertyDispatcher.Enforce(trackedRecord.Key, trackedRecord)) { if (!AssociatedTopic.IsNew) { @@ -645,7 +645,7 @@ protected override void ClearItems() { /// The object which is being inserted. protected bool AllowClean(TItem item) { Contract.Requires(item, nameof(item)); - var topic = item.Value as Topic; + var topic = item.Value as Topic; if (topic is not null && topic.IsNew) { return false; } diff --git a/OnTopic/Internal/Diagnostics/Contract.cs b/OnTopic/Internal/Diagnostics/Contract.cs index 3ae8d691..14b6ce01 100644 --- a/OnTopic/Internal/Diagnostics/Contract.cs +++ b/OnTopic/Internal/Diagnostics/Contract.cs @@ -58,7 +58,7 @@ public static class Contract { /// public static void Requires( bool isValid, - string? errorMessage = null, + string? errorMessage = null, [CallerArgumentExpression(nameof(isValid))] string? expression = null ) => Requires(isValid, errorMessage, expression); @@ -80,7 +80,7 @@ public static void Requires( #pragma warning disable CS8777 // Parameter must have a non-null value when exiting. public static T Requires( [AllowNull, ValidatedNotNull, NotNull]T requiredObject, - string? errorMessage = null, + string? errorMessage = null, [CallerArgumentExpression(nameof(requiredObject))] string? expression = null ) { Requires(requiredObject is not null, errorMessage, expression); @@ -111,7 +111,7 @@ public static T Requires( /// public static void Requires( bool isValid, - string? errorMessage = null, + string? errorMessage = null, [CallerArgumentExpression(nameof(isValid))] string? expression = null ) where T : Exception, new() { if (isValid) return; @@ -161,7 +161,7 @@ or NotSupportedException /// public static void Assume( bool isValid, - string? errorMessage = null, + string? errorMessage = null, [CallerArgumentExpression(nameof(isValid))] string? expression = null ) => Requires(isValid, errorMessage, expression); @@ -191,7 +191,7 @@ public static void Assume( /// public static void Assume( bool isValid, - string? errorMessage = null, + string? errorMessage = null, [CallerArgumentExpression(nameof(isValid))] string? expression = null ) where T : Exception, new() => Requires(isValid, errorMessage, expression); @@ -210,7 +210,7 @@ public static void Assume( #pragma warning disable CS8777 // Parameter must have a non-null value when exiting. public static void Assume( [ValidatedNotNull, NotNull]object? requiredObject, - string? errorMessage = null, + string? errorMessage = null, [CallerArgumentExpression(nameof(requiredObject))] string? expression = null ) => Requires(requiredObject is not null, errorMessage, expression); #pragma warning restore CS8777 // Parameter must have a non-null value when exiting. diff --git a/OnTopic/Internal/Reflection/ItemMetadata.cs b/OnTopic/Internal/Reflection/ItemMetadata.cs index 6d3e6131..57d80a0b 100644 --- a/OnTopic/Internal/Reflection/ItemMetadata.cs +++ b/OnTopic/Internal/Reflection/ItemMetadata.cs @@ -115,7 +115,7 @@ bool isList() /// internal ItemConfiguration Configuration { get { - field ??= new(this); + field ??= new(this); return field; } } @@ -187,7 +187,7 @@ internal ItemConfiguration Configuration { /// internal List CustomAttributes { get { - field ??= [.. _attributeProvider.GetCustomAttributes(true).OfType()]; + field ??= [.. _attributeProvider.GetCustomAttributes(true).OfType()]; return field; } } diff --git a/OnTopic/Internal/Reflection/MemberAccessor.cs b/OnTopic/Internal/Reflection/MemberAccessor.cs index 9aac49d8..247aa15f 100644 --- a/OnTopic/Internal/Reflection/MemberAccessor.cs +++ b/OnTopic/Internal/Reflection/MemberAccessor.cs @@ -198,7 +198,7 @@ internal void SetValue(object target, object? value, bool allowConversion = fals //Proceed with conversion } else if (allowConversion && value is string) { - valueObject = AttributeValueConverter.Convert(value as string, Type); + valueObject = AttributeValueConverter.Convert(value as string, Type); } if (valueObject is null && !IsNullable) { @@ -325,7 +325,7 @@ private Type GetType(MemberInfo memberInfo) { parameters.Length == 0, $"The '{memberInfo.Name}()' method must not expect any parameters if the return type is not void." ); - CanRead = true; + CanRead = true; return methodInfo.ReturnType; } @@ -338,7 +338,7 @@ private Type GetType(MemberInfo memberInfo) { $"will be used as the value of the setter." ); - CanWrite = true; + CanWrite = true; return parameters[0].ParameterType; } diff --git a/OnTopic/Internal/Reflection/TopicPropertyDispatcher{TItem,TValue,TAttributeType}.cs b/OnTopic/Internal/Reflection/TopicPropertyDispatcher{TItem,TValue,TAttributeType}.cs index 1cd20f5f..c8b387df 100644 --- a/OnTopic/Internal/Reflection/TopicPropertyDispatcher{TItem,TValue,TAttributeType}.cs +++ b/OnTopic/Internal/Reflection/TopicPropertyDispatcher{TItem,TValue,TAttributeType}.cs @@ -100,7 +100,7 @@ internal sealed class TopicPropertyDispatcher /// /// The whose properties should be called, when appropriate. internal TopicPropertyDispatcher(Topic associatedTopic) { - _associatedTopic = associatedTopic; + _associatedTopic = associatedTopic; } /*============================================================================================================================ @@ -173,9 +173,9 @@ internal TopicPropertyDispatcher(Topic associatedTopic) { /// /// The object which is being inserted. internal bool Register(string itemKey, TItem? initialValue) { - var type = (Type?)null; + var type = (Type?)null; if (!AttributeValueConverter.IsConvertible(typeof(TValue))) { - type = typeof(TValue); + type = typeof(TValue); } if ( !PropertyCache.ContainsKey(itemKey) && @@ -251,7 +251,7 @@ internal bool Enforce(string itemKey, TItem? initialObject) { #pragma warning restore CA1853 // Unnecessary call to 'Dictionary.ContainsKey(key)' else if (Register(itemKey, initialObject)) { try { - var typeAccessor = TypeAccessorCache.GetTypeAccessor(_associatedTopic.GetType()); + var typeAccessor = TypeAccessorCache.GetTypeAccessor(_associatedTopic.GetType()); typeAccessor.SetPropertyValue(_associatedTopic, itemKey, initialObject?.Value, true); } catch (TargetInvocationException ex) { diff --git a/OnTopic/Internal/Reflection/TypeAccessor.cs b/OnTopic/Internal/Reflection/TypeAccessor.cs index ba1e777e..f506d72d 100644 --- a/OnTopic/Internal/Reflection/TypeAccessor.cs +++ b/OnTopic/Internal/Reflection/TypeAccessor.cs @@ -179,7 +179,7 @@ internal ConstructorInfo GetPrimaryConstructor() => /// Optional, the expected. /// Optional, the expected on the property. internal bool HasGettableProperty(string propertyName, Type? targetType = null, Type? attributeFlag = null) { - var property = GetMember(propertyName); + var property = GetMember(propertyName); return ( property is not null and { CanRead: true, MemberType: MemberTypes.Property } && property.IsSettable(targetType, true) && @@ -206,7 +206,7 @@ internal bool HasGettableProperty(string propertyName, Type? targetType = nul /// Optional, the expected. /// Optional, the expected on the property. internal bool HasGettableMethod(string methodName, Type? targetType = null, Type? attributeFlag = null) { - var method = GetMember(methodName); + var method = GetMember(methodName); return ( method is not null and { CanRead: true, MemberType: MemberTypes.Method } && method.IsSettable(targetType, true) && @@ -234,7 +234,7 @@ internal bool HasGettableMethod(string name, Type? targetType = null) where T /*-------------------------------------------------------------------------------------------------------------------------- | Retrieve member \-------------------------------------------------------------------------------------------------------------------------*/ - var member = GetMember(memberName); + var member = GetMember(memberName); if (member is null) { return null; @@ -292,7 +292,7 @@ internal bool HasGettableMethod(string name, Type? targetType = null) where T /// Optional, the expected. /// Optional, the expected on the property. internal bool HasSettableProperty(string propertyName, Type? targetType = null, Type? attributeFlag = null) { - var property = GetMember(propertyName); + var property = GetMember(propertyName); return ( property is not null and { CanWrite: true, MemberType: MemberTypes.Property } && property.IsSettable(targetType, true) && @@ -320,7 +320,7 @@ internal bool HasSettableProperty(string propertyName, Type? targetType = nul /// Optional, the expected. /// Optional, the expected on the property. internal bool HasSettableMethod(string methodName, Type? targetType = null, Type? attributeFlag = null) { - var method = GetMember(methodName); + var method = GetMember(methodName); return ( method is not null and { CanWrite: true, MemberType: MemberTypes.Method } && method.IsSettable(targetType, true) && @@ -350,7 +350,7 @@ internal void SetValue(object target, string memberName, object? value, bool all /*-------------------------------------------------------------------------------------------------------------------------- | Validate dependencies \-------------------------------------------------------------------------------------------------------------------------*/ - var member = GetMember(memberName); + var member = GetMember(memberName); Contract.Assume(member, $"The {memberName} property could not be retrieved."); diff --git a/OnTopic/Lookup/CompositeTypeLookupService.cs b/OnTopic/Lookup/CompositeTypeLookupService.cs index 632c9ceb..41f57615 100644 --- a/OnTopic/Lookup/CompositeTypeLookupService.cs +++ b/OnTopic/Lookup/CompositeTypeLookupService.cs @@ -51,11 +51,11 @@ public CompositeTypeLookupService(params ITypeLookupService[] typeLookupServices \---------------------------------------------------------------------------------------------------------------------------*/ /// public Type? Lookup(params string[] typeNames) { - var type = typeof(object); + var type = typeof(object); if (typeNames is not null) { foreach (var typeName in typeNames) { foreach (var typeLookupService in _typeLookupServices) { - type = typeLookupService.Lookup(typeName); + type = typeLookupService.Lookup(typeName); if (type is not null && type.Name.Equals(typeName, StringComparison.OrdinalIgnoreCase)) { return type; } diff --git a/OnTopic/Lookup/DynamicTypeLookupService.cs b/OnTopic/Lookup/DynamicTypeLookupService.cs index ea969305..dbf938e0 100644 --- a/OnTopic/Lookup/DynamicTypeLookupService.cs +++ b/OnTopic/Lookup/DynamicTypeLookupService.cs @@ -28,7 +28,7 @@ public DynamicTypeLookupService(Func predicate) : base() { /*-------------------------------------------------------------------------------------------------------------------------- | Find target classes \-------------------------------------------------------------------------------------------------------------------------*/ - var matchedTypes = AppDomain + var matchedTypes = AppDomain .CurrentDomain .GetAssemblies() .Where(a => !(a.FullName?.StartsWith("Microsoft", StringComparison.Ordinal) ?? false) && !(a.FullName?.StartsWith("System", StringComparison.Ordinal) ?? false)) diff --git a/OnTopic/Lookup/StaticTypeLookupService.cs b/OnTopic/Lookup/StaticTypeLookupService.cs index 38e46c61..20942046 100644 --- a/OnTopic/Lookup/StaticTypeLookupService.cs +++ b/OnTopic/Lookup/StaticTypeLookupService.cs @@ -34,7 +34,7 @@ public class StaticTypeLookupService: ITypeLookupService { /// /// The list of instances to expose as part of this service. public StaticTypeLookupService( - IEnumerable? types = null + IEnumerable? types = null ) { /*-------------------------------------------------------------------------------------------------------------------------- diff --git a/OnTopic/Mapping/Annotations/AssociationTypes.cs b/OnTopic/Mapping/Annotations/AssociationTypes.cs index fa9b92fb..1283a517 100644 --- a/OnTopic/Mapping/Annotations/AssociationTypes.cs +++ b/OnTopic/Mapping/Annotations/AssociationTypes.cs @@ -102,6 +102,6 @@ public enum AssociationTypes { /// /// Map all association types. /// - All = Parents | Children | Relationships | IncomingRelationships | MappedCollections | References + All = Parents | Children | Relationships | IncomingRelationships | MappedCollections | References } //Enum \ No newline at end of file diff --git a/OnTopic/Mapping/Annotations/AttributeKeyAttribute.cs b/OnTopic/Mapping/Annotations/AttributeKeyAttribute.cs index 89de1d60..f25c197c 100644 --- a/OnTopic/Mapping/Annotations/AttributeKeyAttribute.cs +++ b/OnTopic/Mapping/Annotations/AttributeKeyAttribute.cs @@ -32,7 +32,7 @@ public sealed class AttributeKeyAttribute : Attribute { /// The key value of the attribute associated with the current property. public AttributeKeyAttribute(string key) { TopicFactory.ValidateKey(key, false); - Key = key; + Key = key; } /*============================================================================================================================ diff --git a/OnTopic/Mapping/Annotations/CollectionAttribute.cs b/OnTopic/Mapping/Annotations/CollectionAttribute.cs index 725054f9..56b02ea0 100644 --- a/OnTopic/Mapping/Annotations/CollectionAttribute.cs +++ b/OnTopic/Mapping/Annotations/CollectionAttribute.cs @@ -40,7 +40,7 @@ public sealed class CollectionAttribute : Attribute { /// The key value of the collection associated with the current property. public CollectionAttribute(string key) { TopicFactory.ValidateKey(key, false); - Key = key; + Key = key; } /// @@ -48,7 +48,7 @@ public CollectionAttribute(string key) { /// /// Optional. The type of collection the collection is associated with. public CollectionAttribute(CollectionType type = CollectionType.Any) { - Type = type; + Type = type; } /*============================================================================================================================ diff --git a/OnTopic/Mapping/Annotations/FilterByAttributeAttribute.cs b/OnTopic/Mapping/Annotations/FilterByAttributeAttribute.cs index b8c76e71..838b0045 100644 --- a/OnTopic/Mapping/Annotations/FilterByAttributeAttribute.cs +++ b/OnTopic/Mapping/Annotations/FilterByAttributeAttribute.cs @@ -43,8 +43,8 @@ public FilterByAttributeAttribute(string key, string value) { /*-------------------------------------------------------------------------------------------------------------------------- | Set properties \-------------------------------------------------------------------------------------------------------------------------*/ - Key = key; - Value = value; + Key = key; + Value = value; } diff --git a/OnTopic/Mapping/Annotations/FilterByContentType.cs b/OnTopic/Mapping/Annotations/FilterByContentType.cs index 5729a54f..da042567 100644 --- a/OnTopic/Mapping/Annotations/FilterByContentType.cs +++ b/OnTopic/Mapping/Annotations/FilterByContentType.cs @@ -29,7 +29,7 @@ public sealed class FilterByContentTypeAttribute : Attribute { /// The content type to filter by. public FilterByContentTypeAttribute(string contentType) { TopicFactory.ValidateKey(contentType, false); - ContentType = contentType; + ContentType = contentType; } /*============================================================================================================================ diff --git a/OnTopic/Mapping/Annotations/IncludeAttribute.cs b/OnTopic/Mapping/Annotations/IncludeAttribute.cs index fb06d3d0..eac25180 100644 --- a/OnTopic/Mapping/Annotations/IncludeAttribute.cs +++ b/OnTopic/Mapping/Annotations/IncludeAttribute.cs @@ -35,7 +35,7 @@ public sealed class IncludeAttribute : Attribute { /// /// The specific associations that should be crawled. public IncludeAttribute(AssociationTypes associations) { - Associations = associations; + Associations = associations; } /*============================================================================================================================ diff --git a/OnTopic/Mapping/Annotations/MapAsAttribute.cs b/OnTopic/Mapping/Annotations/MapAsAttribute.cs index b4794b85..077b10fb 100644 --- a/OnTopic/Mapping/Annotations/MapAsAttribute.cs +++ b/OnTopic/Mapping/Annotations/MapAsAttribute.cs @@ -41,7 +41,7 @@ public sealed class MapAsAttribute : Attribute { /// /// The view model to map the association to. public MapAsAttribute(Type type) { - Type = type; + Type = type; } /*============================================================================================================================ diff --git a/OnTopic/Mapping/Annotations/MapToParentAttribute.cs b/OnTopic/Mapping/Annotations/MapToParentAttribute.cs index 63a80404..6d28c789 100644 --- a/OnTopic/Mapping/Annotations/MapToParentAttribute.cs +++ b/OnTopic/Mapping/Annotations/MapToParentAttribute.cs @@ -52,7 +52,7 @@ public string? AttributePrefix { get => field; set { TopicFactory.ValidateKey(value, true); - field = value; + field = value; } } diff --git a/OnTopic/Mapping/Annotations/MetadataAttribute.cs b/OnTopic/Mapping/Annotations/MetadataAttribute.cs index 95e32b9a..f11eb0dc 100644 --- a/OnTopic/Mapping/Annotations/MetadataAttribute.cs +++ b/OnTopic/Mapping/Annotations/MetadataAttribute.cs @@ -30,7 +30,7 @@ public sealed class MetadataAttribute : Attribute { /// The key represents the name of the Metadata topic that should be mapped to. public MetadataAttribute(string key) { TopicFactory.ValidateKey(key, false); - Key = key; + Key = key; } /*============================================================================================================================ diff --git a/OnTopic/Mapping/CachedTopicMappingService.cs b/OnTopic/Mapping/CachedTopicMappingService.cs index 4b161207..6f6f56f4 100644 --- a/OnTopic/Mapping/CachedTopicMappingService.cs +++ b/OnTopic/Mapping/CachedTopicMappingService.cs @@ -44,7 +44,7 @@ public class CachedTopicMappingService(ITopicMappingService topicMappingService) /*-------------------------------------------------------------------------------------------------------------------------- | Ensure cache is populated \-------------------------------------------------------------------------------------------------------------------------*/ - var cacheKey = (topic.Id, (Type?)null, associations); + var cacheKey = (topic.Id, (Type?)null, associations); if(_cache.TryGetValue(cacheKey, out var viewModel)) { return viewModel; } @@ -52,7 +52,7 @@ public class CachedTopicMappingService(ITopicMappingService topicMappingService) /*-------------------------------------------------------------------------------------------------------------------------- | Process result \-------------------------------------------------------------------------------------------------------------------------*/ - viewModel = await _topicMappingService.MapAsync(topic, associations).ConfigureAwait(false); + viewModel = await _topicMappingService.MapAsync(topic, associations).ConfigureAwait(false); /*-------------------------------------------------------------------------------------------------------------------------- | Return (cached) result @@ -82,7 +82,7 @@ public class CachedTopicMappingService(ITopicMappingService topicMappingService) /*-------------------------------------------------------------------------------------------------------------------------- | Ensure cache is populated \-------------------------------------------------------------------------------------------------------------------------*/ - var cacheKey = (topic.Id, typeof(T), associations); + var cacheKey = (topic.Id, typeof(T), associations); if (_cache.TryGetValue(cacheKey, out var viewModel)) { return (T)viewModel; } @@ -90,7 +90,7 @@ public class CachedTopicMappingService(ITopicMappingService topicMappingService) /*-------------------------------------------------------------------------------------------------------------------------- | Process result \-------------------------------------------------------------------------------------------------------------------------*/ - viewModel = await _topicMappingService.MapAsync(topic, associations).ConfigureAwait(false); + viewModel = await _topicMappingService.MapAsync(topic, associations).ConfigureAwait(false); /*-------------------------------------------------------------------------------------------------------------------------- | Return (cached) result @@ -125,7 +125,7 @@ public class CachedTopicMappingService(ITopicMappingService topicMappingService) /*-------------------------------------------------------------------------------------------------------------------------- | Ensure cache is populated \-------------------------------------------------------------------------------------------------------------------------*/ - var cacheKey = (topic.Id, target.GetType(), associations); + var cacheKey = (topic.Id, target.GetType(), associations); if (_cache.TryGetValue(cacheKey, out var viewModel)) { return viewModel; } @@ -133,7 +133,7 @@ public class CachedTopicMappingService(ITopicMappingService topicMappingService) /*-------------------------------------------------------------------------------------------------------------------------- | Process result \-------------------------------------------------------------------------------------------------------------------------*/ - viewModel = await _topicMappingService.MapAsync(topic, associations).ConfigureAwait(false); + viewModel = await _topicMappingService.MapAsync(topic, associations).ConfigureAwait(false); /*-------------------------------------------------------------------------------------------------------------------------- | Return (cached) result @@ -192,7 +192,7 @@ public class CachedTopicMappingService(ITopicMappingService topicMappingService) _cache.TryAdd(cacheKey, viewModel); } if (cacheKey.Item2 is not null) { - cacheKey = (cacheKey.Item1, null, cacheKey.Item3); + cacheKey = (cacheKey.Item1, null, cacheKey.Item3); } if ( cacheKey.Item1 > 0 && ( diff --git a/OnTopic/Mapping/Hierarchical/CachedHierarchicalTopicMappingService{T}.cs b/OnTopic/Mapping/Hierarchical/CachedHierarchicalTopicMappingService{T}.cs index 0b62d1c4..05c4049f 100644 --- a/OnTopic/Mapping/Hierarchical/CachedHierarchicalTopicMappingService{T}.cs +++ b/OnTopic/Mapping/Hierarchical/CachedHierarchicalTopicMappingService{T}.cs @@ -62,7 +62,7 @@ IHierarchicalTopicMappingService hierarchicalTopicMappingService /// public async Task GetRootViewModelAsync( Topic? sourceTopic, - int tiers = 1, + int tiers = 1, Func? validationDelegate = null ) { @@ -83,7 +83,7 @@ IHierarchicalTopicMappingService hierarchicalTopicMappingService /*-------------------------------------------------------------------------------------------------------------------------- | Cache and return new version \-------------------------------------------------------------------------------------------------------------------------*/ - var viewModel = await GetViewModelAsync(sourceTopic, tiers, validationDelegate).ConfigureAwait(false); + var viewModel = await GetViewModelAsync(sourceTopic, tiers, validationDelegate).ConfigureAwait(false); return _cache.GetOrAdd(sourceTopic.Id, viewModel); } @@ -94,7 +94,7 @@ IHierarchicalTopicMappingService hierarchicalTopicMappingService /// public async Task GetViewModelAsync( Topic? sourceTopic, - int tiers = 1, + int tiers = 1, Func? validationDelegate = null ) => await _hierarchicalTopicMappingService.GetViewModelAsync(sourceTopic, tiers, validationDelegate).ConfigureAwait(false); diff --git a/OnTopic/Mapping/Hierarchical/HierarchicalTopicMappingService{T}.cs b/OnTopic/Mapping/Hierarchical/HierarchicalTopicMappingService{T}.cs index 797fd2cc..3b2a4642 100644 --- a/OnTopic/Mapping/Hierarchical/HierarchicalTopicMappingService{T}.cs +++ b/OnTopic/Mapping/Hierarchical/HierarchicalTopicMappingService{T}.cs @@ -65,14 +65,14 @@ public class HierarchicalTopicMappingService(ITopicRepository topicRepository /*-------------------------------------------------------------------------------------------------------------------------- | Establish variables \-------------------------------------------------------------------------------------------------------------------------*/ - var navigationRootTopic = currentTopic; + var navigationRootTopic = currentTopic; /*-------------------------------------------------------------------------------------------------------------------------- | Handle default, if necessary \-------------------------------------------------------------------------------------------------------------------------*/ if (navigationRootTopic is null) { Contract.Assume(!String.IsNullOrEmpty(defaultRoot), nameof(defaultRoot)); - navigationRootTopic = TopicRepository.Load(defaultRoot, currentTopic).GetAwaiter().GetResult(); + navigationRootTopic = TopicRepository.Load(defaultRoot, currentTopic).GetAwaiter().GetResult(); } /*-------------------------------------------------------------------------------------------------------------------------- @@ -88,7 +88,7 @@ public class HierarchicalTopicMappingService(ITopicRepository topicRepository | Find navigation root \-------------------------------------------------------------------------------------------------------------------------*/ while (navigationRootTopic is not null && DistanceFromRoot(navigationRootTopic) > fromRoot) { - navigationRootTopic = navigationRootTopic.Parent; + navigationRootTopic = navigationRootTopic.Parent; } /*-------------------------------------------------------------------------------------------------------------------------- @@ -106,9 +106,9 @@ public class HierarchicalTopicMappingService(ITopicRepository topicRepository /// /// The to pull the values from. private static int DistanceFromRoot(Topic sourceTopic) { - var distance = 1; + var distance = 1; while (sourceTopic.Parent is not null) { - sourceTopic = sourceTopic.Parent; + sourceTopic = sourceTopic.Parent; distance++; } return distance; @@ -120,7 +120,7 @@ private static int DistanceFromRoot(Topic sourceTopic) { /// public virtual async Task GetRootViewModelAsync( Topic? sourceTopic, - int tiers = 1, + int tiers = 1, Func? validationDelegate = null ) => await GetViewModelAsync(sourceTopic, tiers, validationDelegate).ConfigureAwait(false); @@ -130,7 +130,7 @@ private static int DistanceFromRoot(Topic sourceTopic) { /// public async Task GetViewModelAsync( Topic? sourceTopic, - int tiers = 1, + int tiers = 1, Func? validationDelegate = null ) { @@ -152,12 +152,12 @@ private static int DistanceFromRoot(Topic sourceTopic) { /*-------------------------------------------------------------------------------------------------------------------------- | Establish default delegate \-------------------------------------------------------------------------------------------------------------------------*/ - validationDelegate ??= (Topic) => true; + validationDelegate ??= (Topic) => true; /*-------------------------------------------------------------------------------------------------------------------------- | Map object \-------------------------------------------------------------------------------------------------------------------------*/ - viewModel = await _topicMappingService.MapAsync(sourceTopic, AssociationTypes.None).ConfigureAwait(false); + viewModel = await _topicMappingService.MapAsync(sourceTopic, AssociationTypes.None).ConfigureAwait(false); Contract.Assume( viewModel, diff --git a/OnTopic/Mapping/Hierarchical/IHierarchicalTopicMappingService{T}.cs b/OnTopic/Mapping/Hierarchical/IHierarchicalTopicMappingService{T}.cs index 550f3c71..4bffb1f3 100644 --- a/OnTopic/Mapping/Hierarchical/IHierarchicalTopicMappingService{T}.cs +++ b/OnTopic/Mapping/Hierarchical/IHierarchicalTopicMappingService{T}.cs @@ -73,7 +73,7 @@ namespace OnTopic.Mapping.Hierarchical; /// Task GetRootViewModelAsync( Topic? sourceTopic, - int tiers = 1, + int tiers = 1, Func? validationDelegate = null ); @@ -93,7 +93,7 @@ namespace OnTopic.Mapping.Hierarchical; /// Task GetViewModelAsync( Topic? sourceTopic, - int tiers = 1, + int tiers = 1, Func? validationDelegate = null ); diff --git a/OnTopic/Mapping/Internal/AssociationMap.cs b/OnTopic/Mapping/Internal/AssociationMap.cs index 0d126531..a2459359 100644 --- a/OnTopic/Mapping/Internal/AssociationMap.cs +++ b/OnTopic/Mapping/Internal/AssociationMap.cs @@ -26,7 +26,7 @@ static internal class AssociationMap { \---------------------------------------------------------------------------------------------------------------------------*/ static AssociationMap() { - var mappings = new Dictionary { + var mappings = new Dictionary { { CollectionType.Any, AssociationTypes.None }, { CollectionType.Children, AssociationTypes.Children }, { CollectionType.Relationship, AssociationTypes.Relationships }, diff --git a/OnTopic/Mapping/Internal/ItemConfiguration.cs b/OnTopic/Mapping/Internal/ItemConfiguration.cs index 06a6da48..8d706932 100644 --- a/OnTopic/Mapping/Internal/ItemConfiguration.cs +++ b/OnTopic/Mapping/Internal/ItemConfiguration.cs @@ -86,19 +86,19 @@ internal ItemConfiguration(ItemMetadata itemMetadata) { \-------------------------------------------------------------------------------------------------------------------------*/ GetAttributeValue( a => { - CollectionKey = a.Key ?? CollectionKey; - CollectionType = a.Type; + CollectionKey = a.Key ?? CollectionKey; + CollectionType = a.Type; } ); if (CollectionKey.Equals("Children", StringComparison.OrdinalIgnoreCase)) { - CollectionType = CollectionType.Children; + CollectionType = CollectionType.Children; } /*-------------------------------------------------------------------------------------------------------------------------- | Attributes: Set attribute filters \-------------------------------------------------------------------------------------------------------------------------*/ - var filterByAttributes = CustomAttributes.OfType().ToArray(); + var filterByAttributes = CustomAttributes.OfType().ToArray(); if (filterByAttributes.Length > 0) { foreach (var filter in filterByAttributes) { AttributeFilters.Add(filter.Key, filter.Value); @@ -468,7 +468,7 @@ internal bool SatisfiesAttributeFilters(Topic source) => /// An type to evaluate. /// The to execute on the attribute. private void GetAttributeValue(Action action) where T : Attribute { - var attribute = GetAttribute(); + var attribute = GetAttribute(); if (attribute is not null) { action(attribute); } diff --git a/OnTopic/Mapping/Internal/MappedTopicCache.cs b/OnTopic/Mapping/Internal/MappedTopicCache.cs index 6cd48313..11be1494 100644 --- a/OnTopic/Mapping/Internal/MappedTopicCache.cs +++ b/OnTopic/Mapping/Internal/MappedTopicCache.cs @@ -35,10 +35,10 @@ internal sealed class MappedTopicCache { /// Returns true if a cached entry could be found, and otherwise false. internal bool TryGetValue(int topicId, Type type, [NotNullWhen(true)] out MappedTopicCacheEntry? cacheEntry) { if (_cache.TryGetValue(GetCacheKey(topicId, type), out var existingCacheEntry) && !existingCacheEntry.IsInitializing) { - cacheEntry = existingCacheEntry; + cacheEntry = existingCacheEntry; return true; }; - cacheEntry = null; + cacheEntry = null; return false; } @@ -68,7 +68,7 @@ internal void Register(int topicId, AssociationTypes associations, object viewMo | Get or add entry \-------------------------------------------------------------------------------------------------------------------------*/ if (topicId > 0 && !type.Equals(typeof(object))) { - cacheEntry = _cache.GetOrAdd(cacheKey, cacheEntry); + cacheEntry = _cache.GetOrAdd(cacheKey, cacheEntry); if (cacheEntry.IsInitializing) { cacheEntry.IsInitializing = false; cacheEntry.MappedTopic = viewModel; @@ -92,9 +92,9 @@ internal MappedTopicCacheEntry Preregister(int topicId, Type type) { /*-------------------------------------------------------------------------------------------------------------------------- | Construct cache entry \-------------------------------------------------------------------------------------------------------------------------*/ - var cacheKey = GetCacheKey(topicId, type); - var cacheEntry = new MappedTopicCacheEntry() { - IsInitializing = true + var cacheKey = GetCacheKey(topicId, type); + var cacheEntry = new MappedTopicCacheEntry() { + IsInitializing = true }; /*-------------------------------------------------------------------------------------------------------------------------- diff --git a/OnTopic/Mapping/Reverse/BindingModelValidator.cs b/OnTopic/Mapping/Reverse/BindingModelValidator.cs index 9d124a11..93d42059 100644 --- a/OnTopic/Mapping/Reverse/BindingModelValidator.cs +++ b/OnTopic/Mapping/Reverse/BindingModelValidator.cs @@ -148,7 +148,7 @@ static internal void ValidateProperty( | Define variables \-------------------------------------------------------------------------------------------------------------------------*/ var configuration = propertyAccessor.Configuration; - var compositeAttributeKey = configuration.GetCompositeAttributeKey(attributePrefix); + var compositeAttributeKey = configuration.GetCompositeAttributeKey(attributePrefix); var attributeDescriptor = contentTypeDescriptor.AttributeDescriptors.GetValue(compositeAttributeKey); var childCollections = new[] { CollectionType.Children, CollectionType.NestedTopics }; var relationships = new[] { CollectionType.Relationship, CollectionType.IncomingRelationship }; @@ -188,7 +188,7 @@ static internal void ValidateProperty( foreach (var type in propertyAccessor.Type.GetInterfaces()) { if (type.IsGenericType && typeof(IList<>) == type.GetGenericTypeDefinition()) { //Uses last argument in case it's a KeyedCollection; in that case, we want the TItem type - listType = type.GetGenericArguments().Last(); + listType = type.GetGenericArguments().Last(); } } diff --git a/OnTopic/Mapping/Reverse/ReverseTopicMappingService.cs b/OnTopic/Mapping/Reverse/ReverseTopicMappingService.cs index 9781fe47..57d4acc1 100644 --- a/OnTopic/Mapping/Reverse/ReverseTopicMappingService.cs +++ b/OnTopic/Mapping/Reverse/ReverseTopicMappingService.cs @@ -77,7 +77,7 @@ public ReverseTopicMappingService(ITopicRepository topicRepository) { /*-------------------------------------------------------------------------------------------------------------------------- | Instantiate target \-------------------------------------------------------------------------------------------------------------------------*/ - var topic = TopicFactory.Create(source.Key, source.ContentType); + var topic = TopicFactory.Create(source.Key, source.ContentType); /*-------------------------------------------------------------------------------------------------------------------------- | Provide mapping @@ -194,7 +194,7 @@ public ReverseTopicMappingService(ITopicRepository topicRepository) { | Validate model \-------------------------------------------------------------------------------------------------------------------------*/ var typeAccessor = TypeAccessorCache.GetTypeAccessor(source.GetType()); - var contentTypeDescriptor = _contentTypeDescriptors.GetValue(target.ContentType); + var contentTypeDescriptor = _contentTypeDescriptors.GetValue(target.ContentType); BindingModelValidator.ValidateModel(typeAccessor, contentTypeDescriptor, attributePrefix); @@ -239,8 +239,8 @@ private async Task SetPropertyAsync( | Establish per-property variables \-------------------------------------------------------------------------------------------------------------------------*/ var configuration = memberAccessor.Configuration; - var contentTypeDescriptor = _contentTypeDescriptors.GetValue(target.ContentType); - var compositeAttributeKey = configuration.GetCompositeAttributeKey(attributePrefix); + var contentTypeDescriptor = _contentTypeDescriptors.GetValue(target.ContentType); + var compositeAttributeKey = configuration.GetCompositeAttributeKey(attributePrefix); Contract.Assume(contentTypeDescriptor, nameof(contentTypeDescriptor)); @@ -273,7 +273,7 @@ await MapAsync( /*-------------------------------------------------------------------------------------------------------------------------- | Retrieve attribute descriptor \-------------------------------------------------------------------------------------------------------------------------*/ - var attributeType = contentTypeDescriptor.AttributeDescriptors.GetValue(compositeAttributeKey); + var attributeType = contentTypeDescriptor.AttributeDescriptors.GetValue(compositeAttributeKey); if (attributeType is null) { throw new MappingModelValidationException( diff --git a/OnTopic/Mapping/TopicMappingService.cs b/OnTopic/Mapping/TopicMappingService.cs index 23dc27bf..aa9455e1 100644 --- a/OnTopic/Mapping/TopicMappingService.cs +++ b/OnTopic/Mapping/TopicMappingService.cs @@ -87,7 +87,7 @@ public class TopicMappingService(ITopicRepository topicRepository, ITypeLookupSe /*-------------------------------------------------------------------------------------------------------------------------- | Lookup type \-------------------------------------------------------------------------------------------------------------------------*/ - var viewModelType = _typeLookupService.Lookup($"{topic.ContentType}TopicViewModel", $"{topic.ContentType}ViewModel"); + var viewModelType = _typeLookupService.Lookup($"{topic.ContentType}TopicViewModel", $"{topic.ContentType}ViewModel"); if (viewModelType is null) { throw new InvalidTypeException( @@ -231,7 +231,7 @@ public class TopicMappingService(ITopicRepository topicRepository, ITypeLookupSe /*-------------------------------------------------------------------------------------------------------------------------- | Initialize object \-------------------------------------------------------------------------------------------------------------------------*/ - target = Activator.CreateInstance(type, arguments); + target = Activator.CreateInstance(type, arguments); Contract.Assume( target, @@ -379,7 +379,7 @@ private async Task MapAsync( AssociationTypes associations, ParameterMetadata parameter, MappedTopicCache cache, - string? attributePrefix = null + string? attributePrefix = null ) { /*-------------------------------------------------------------------------------------------------------------------------- @@ -410,7 +410,7 @@ private async Task MapAsync( /*-------------------------------------------------------------------------------------------------------------------------- | Determine value \-------------------------------------------------------------------------------------------------------------------------*/ - var value = await GetValue(source, parameter.Type, associations, parameter, cache, attributePrefix, false).ConfigureAwait(false); + var value = await GetValue(source, parameter.Type, associations, parameter, cache, attributePrefix, false).ConfigureAwait(false); if (value is null && parameter.IsList) { return await getList(parameter.Type).ConfigureAwait(false); @@ -423,8 +423,8 @@ private async Task MapAsync( \-------------------------------------------------------------------------------------------------------------------------*/ async Task getList(Type targetType) { - var sourceList = await GetSourceCollectionAsync(source, associations, parameter, attributePrefix).ConfigureAwait(false); - var targetList = InitializeCollection(targetType); + var sourceList = await GetSourceCollectionAsync(source, associations, parameter, attributePrefix).ConfigureAwait(false); + var targetList = InitializeCollection(targetType); if (targetList is null) { return null; @@ -478,7 +478,7 @@ private async Task SetPropertyAsync( | Handle [MapToParent] attribute \-------------------------------------------------------------------------------------------------------------------------*/ if (configuration.MapToParent) { - var targetProperty = propertyAccessor.GetValue(target); + var targetProperty = propertyAccessor.GetValue(target); if (targetProperty is not null) { await MapAsync( source, @@ -494,7 +494,7 @@ await MapAsync( | Determine value \-------------------------------------------------------------------------------------------------------------------------*/ else { - var value = await GetValue(source, propertyAccessor.Type, associations, propertyAccessor, cache, attributePrefix, mapAssociationsOnly).ConfigureAwait(false); + var value = await GetValue(source, propertyAccessor.Type, associations, propertyAccessor, cache, attributePrefix, mapAssociationsOnly).ConfigureAwait(false); if (value is null && propertyAccessor.IsList) { await SetCollectionValueAsync(source, target, associations, propertyAccessor, cache, attributePrefix).ConfigureAwait(false); } @@ -543,18 +543,18 @@ await MapAsync( \-------------------------------------------------------------------------------------------------------------------------*/ var value = (object?)null; if (!mapAssociationsOnly && configuration.DefaultValue is not null) { - value = configuration.DefaultValue; + value = configuration.DefaultValue; } /*-------------------------------------------------------------------------------------------------------------------------- | Handle by type, attribute \-------------------------------------------------------------------------------------------------------------------------*/ if (TryGetCompatibleProperty(source, targetType, itemMetadata, attributePrefix, out var compatibleValue)) { - value = compatibleValue; + value = compatibleValue; } else if (itemMetadata.IsConvertible) { if (!mapAssociationsOnly) { - value = GetScalarValue(source, itemMetadata, attributePrefix); + value = GetScalarValue(source, itemMetadata, attributePrefix); } } else if (itemMetadata.IsList) { @@ -562,16 +562,16 @@ await MapAsync( } else if (configuration.GetCompositeAttributeKey(attributePrefix) is "Parent") { if (associations.HasFlag(AssociationTypes.Parents) && source.Parent is not null) { - value = await GetTopicReferenceAsync(source.Parent, targetType, itemMetadata, cache).ConfigureAwait(false); + value = await GetTopicReferenceAsync(source.Parent, targetType, itemMetadata, cache).ConfigureAwait(false); } } else if (configuration.MapToParent) { return null; } else if (itemMetadata.Type.IsClass && associations.HasFlag(AssociationTypes.References)) { - var topicReference = await getTopicReference().ConfigureAwait(false); + var topicReference = await getTopicReference().ConfigureAwait(false); if (topicReference is not null) { - value = await GetTopicReferenceAsync(topicReference, targetType, itemMetadata, cache).ConfigureAwait(false); + value = await GetTopicReferenceAsync(topicReference, targetType, itemMetadata, cache).ConfigureAwait(false); } } @@ -643,20 +643,20 @@ await MapAsync( | Attempt to retrieve value from topic.{Property} \-------------------------------------------------------------------------------------------------------------------------*/ if (maybeCompatible) { - attributeValue = typeAccessor.GetMethodValue(source, $"Get{configuration.GetCompositeAttributeKey(attributePrefix)}")?.ToString(); + attributeValue = typeAccessor.GetMethodValue(source, $"Get{configuration.GetCompositeAttributeKey(attributePrefix)}")?.ToString(); } /*-------------------------------------------------------------------------------------------------------------------------- | Attempt to retrieve value from topic.{Property} \-------------------------------------------------------------------------------------------------------------------------*/ if (maybeCompatible && attributeValue is null) { - attributeValue = typeAccessor.GetPropertyValue(source, configuration.GetCompositeAttributeKey(attributePrefix))?.ToString(); + attributeValue = typeAccessor.GetPropertyValue(source, configuration.GetCompositeAttributeKey(attributePrefix))?.ToString(); } /*-------------------------------------------------------------------------------------------------------------------------- | Otherwise, attempt to retrieve value from topic.Attributes.GetValue({Property}) \-------------------------------------------------------------------------------------------------------------------------*/ - attributeValue ??= source.Attributes.GetValue( + attributeValue ??= source.Attributes.GetValue( configuration.GetCompositeAttributeKey(attributePrefix), configuration.DefaultValue?.ToString(), configuration.InheritValue @@ -741,9 +741,9 @@ private async Task SetCollectionValueAsync( /*-------------------------------------------------------------------------------------------------------------------------- | Ensure target list is created \-------------------------------------------------------------------------------------------------------------------------*/ - var targetList = (IList?)memberAccessor.GetValue(target); + var targetList = (IList?)memberAccessor.GetValue(target); if (targetList is null) { - targetList = InitializeCollection(memberAccessor.Type); + targetList = InitializeCollection(memberAccessor.Type); memberAccessor.SetValue(target, targetList); } @@ -756,7 +756,7 @@ private async Task SetCollectionValueAsync( /*-------------------------------------------------------------------------------------------------------------------------- | Establish source collection to store topics to be mapped \-------------------------------------------------------------------------------------------------------------------------*/ - var sourceList = await GetSourceCollectionAsync(source, associations, memberAccessor, attributePrefix).ConfigureAwait(false); + var sourceList = await GetSourceCollectionAsync(source, associations, memberAccessor, attributePrefix).ConfigureAwait(false); /*-------------------------------------------------------------------------------------------------------------------------- | Validate that source collection was identified @@ -811,7 +811,7 @@ private async Task> GetSourceCollectionAsync( /*-------------------------------------------------------------------------------------------------------------------------- | Handle children \-------------------------------------------------------------------------------------------------------------------------*/ - listSource = getCollection( + listSource = getCollection( CollectionType.Children, s => true, () => [.. source.Children] @@ -820,7 +820,7 @@ private async Task> GetSourceCollectionAsync( /*-------------------------------------------------------------------------------------------------------------------------- | Handle (outgoing) relationships \-------------------------------------------------------------------------------------------------------------------------*/ - listSource = getCollection( + listSource = getCollection( CollectionType.Relationship, source.Relationships.Contains, () => source.Relationships.GetValues(collectionKey) @@ -829,7 +829,7 @@ private async Task> GetSourceCollectionAsync( /*-------------------------------------------------------------------------------------------------------------------------- | Handle nested topics, or children corresponding to the property name \-------------------------------------------------------------------------------------------------------------------------*/ - listSource = getCollection( + listSource = getCollection( CollectionType.NestedTopics, source.Children.Contains, () => source.Children[collectionKey].Children @@ -838,7 +838,7 @@ private async Task> GetSourceCollectionAsync( /*-------------------------------------------------------------------------------------------------------------------------- | Handle (incoming) relationships \-------------------------------------------------------------------------------------------------------------------------*/ - listSource = getCollection( + listSource = getCollection( CollectionType.IncomingRelationship, source.IncomingRelationships.Contains, () => source.IncomingRelationships.GetValues(collectionKey) @@ -852,13 +852,13 @@ private async Task> GetSourceCollectionAsync( //For example, the ContentTypeDescriptor's AttributeDescriptors collection, which provides a rollup of //AttributeDescriptors from the current ContentTypeDescriptor, as well as all of its ascendents. if (listSource.Count == 0) { - var sourceProperty = TypeAccessorCache.GetTypeAccessor(source.GetType()).GetMember(configuration.GetCompositeAttributeKey(attributePrefix)); + var sourceProperty = TypeAccessorCache.GetTypeAccessor(source.GetType()).GetMember(configuration.GetCompositeAttributeKey(attributePrefix)); if ( sourceProperty?.GetValue(source) is IList sourcePropertyValue && sourcePropertyValue.Count > 0 && sourcePropertyValue[0] is Topic ) { - listSource = getCollection( + listSource = getCollection( CollectionType.MappedCollection, s => true, () => [.. sourcePropertyValue.Cast()] @@ -870,10 +870,10 @@ sourcePropertyValue[0] is Topic | Handle Metadata relationship \-------------------------------------------------------------------------------------------------------------------------*/ if (listSource.Count == 0 && !String.IsNullOrWhiteSpace(configuration.MetadataKey)) { - var metadataKey = $"Root:Configuration:Metadata:{configuration.MetadataKey}:LookupList"; - var metadataParent = await _topicRepository.Load(metadataKey, source).ConfigureAwait(false); + var metadataKey = $"Root:Configuration:Metadata:{configuration.MetadataKey}:LookupList"; + var metadataParent = await _topicRepository.Load(metadataKey, source).ConfigureAwait(false); if (metadataParent is not null) { - listSource = [.. metadataParent.Children]; + listSource = [.. metadataParent.Children]; } } @@ -883,7 +883,7 @@ sourcePropertyValue[0] is Topic if (configuration.FlattenChildren) { List flattenedList = []; listSource.ToList().ForEach(t => FlattenTopicGraph(t, flattenedList)); - listSource = flattenedList; + listSource = flattenedList; } return listSource; @@ -929,11 +929,11 @@ MappedTopicCache cache /*-------------------------------------------------------------------------------------------------------------------------- | Determine the type of item in the list \-------------------------------------------------------------------------------------------------------------------------*/ - var listType = typeof(ITopicViewModel); + var listType = typeof(ITopicViewModel); foreach (var type in targetList.GetType().GetInterfaces()) { if (type.IsGenericType && typeof(IList<>) == type.GetGenericTypeDefinition()) { //Uses last argument in case it's a KeyedCollection; in that case, we want the TItem type - listType = type.GetGenericArguments().Last(); + listType = type.GetGenericArguments().Last(); } } @@ -1075,7 +1075,7 @@ MappedTopicCache cache var mappingType = GetValidatedMappingType(configuration.MapAs, targetType)?? GetValidatedMappingType(source, targetType); if (mappingType is not null) { - topicDto = await MapAsync(source, mappingType, configuration.IncludeAssociations, cache).ConfigureAwait(false); + topicDto = await MapAsync(source, mappingType, configuration.IncludeAssociations, cache).ConfigureAwait(false); } /*-------------------------------------------------------------------------------------------------------------------------- @@ -1137,7 +1137,7 @@ private static bool TryGetCompatibleProperty(Topic source, Type targetType, Item | Rely on MaybeCompatible to bypass known incompatible types \-------------------------------------------------------------------------------------------------------------------------*/ if (source.GetType() == typeof(Topic) && !itemMetadata.MaybeCompatible) { - value = null; + value = null; return false; }; @@ -1150,14 +1150,14 @@ private static bool TryGetCompatibleProperty(Topic source, Type targetType, Item | Escape clause if preconditions are not met \-------------------------------------------------------------------------------------------------------------------------*/ if (sourcePropertyAccessor is null || !targetType.IsAssignableFrom(sourcePropertyAccessor.Type)) { - value = null; + value = null; return false; } /*-------------------------------------------------------------------------------------------------------------------------- | Return value \-------------------------------------------------------------------------------------------------------------------------*/ - value = sourcePropertyAccessor.GetValue(source); + value = sourcePropertyAccessor.GetValue(source); return true; diff --git a/OnTopic/Metadata/AttributeDescriptor.cs b/OnTopic/Metadata/AttributeDescriptor.cs index f9a71b5e..ddb20960 100644 --- a/OnTopic/Metadata/AttributeDescriptor.cs +++ b/OnTopic/Metadata/AttributeDescriptor.cs @@ -63,8 +63,8 @@ public class AttributeDescriptor : Topic { public AttributeDescriptor( string key, string contentType, - Topic? parent = null, - int id = -1 + Topic? parent = null, + int id = -1 ) : base( key, contentType, diff --git a/OnTopic/Metadata/ContentTypeDescriptor.cs b/OnTopic/Metadata/ContentTypeDescriptor.cs index 96ee4b1e..095de773 100644 --- a/OnTopic/Metadata/ContentTypeDescriptor.cs +++ b/OnTopic/Metadata/ContentTypeDescriptor.cs @@ -64,8 +64,8 @@ public class ContentTypeDescriptor : Topic { public ContentTypeDescriptor( string key, string contentType, - Topic? parent = null, - int id = -1 + Topic? parent = null, + int id = -1 ) : base( key, contentType, diff --git a/OnTopic/Obsolete/Attributes/AttributeValue.cs b/OnTopic/Obsolete/Attributes/AttributeValue.cs index 7cbe16fb..acd753f0 100644 --- a/OnTopic/Obsolete/Attributes/AttributeValue.cs +++ b/OnTopic/Obsolete/Attributes/AttributeValue.cs @@ -99,8 +99,8 @@ internal AttributeValue( string? value, bool isDirty, bool enforceBusinessLogic, - DateTime? lastModified = null, - bool? isExtendedAttribute = null + DateTime? lastModified = null, + bool? isExtendedAttribute = null ) : this( key, value, diff --git a/OnTopic/Obsolete/Collections/AttributeValueCollection.cs b/OnTopic/Obsolete/Collections/AttributeValueCollection.cs index a30ee5a4..0538ca5b 100644 --- a/OnTopic/Obsolete/Collections/AttributeValueCollection.cs +++ b/OnTopic/Obsolete/Collections/AttributeValueCollection.cs @@ -214,9 +214,9 @@ internal AttributeValueCollection(Topic parentTopic) : base(StringComparer.Invar public void SetValue( string key, string? value, - bool? isDirty = null, - DateTime? version = null, - bool? isExtendedAttribute = null + bool? isDirty = null, + DateTime? version = null, + bool? isExtendedAttribute = null ) => SetValue(key, value, isDirty, true, version, isExtendedAttribute); @@ -267,8 +267,8 @@ internal void SetValue( string? value, bool? isDirty, bool enforceBusinessLogic, - DateTime? version = null, - bool? isExtendedAttribute = null + DateTime? version = null, + bool? isExtendedAttribute = null ) => throw new NotImplementedException(); /*============================================================================================================================ diff --git a/OnTopic/Obsolete/Collections/NamedTopicCollection.cs b/OnTopic/Obsolete/Collections/NamedTopicCollection.cs index 62ff941c..8413f465 100644 --- a/OnTopic/Obsolete/Collections/NamedTopicCollection.cs +++ b/OnTopic/Obsolete/Collections/NamedTopicCollection.cs @@ -32,7 +32,7 @@ public class NamedTopicCollection: KeyedTopicCollection { /// Provides a name for the collection, used to identify different collections. /// Optionally seeds the collection with an optional list of topic references. public NamedTopicCollection(string name = "", IEnumerable? topics = null) : base() { - Name = name; + Name = name; if (topics is not null) { CopyTo([.. topics], 0); } diff --git a/OnTopic/Obsolete/Mapping/Annotations/FollowAttribute.cs b/OnTopic/Obsolete/Mapping/Annotations/FollowAttribute.cs index ab991129..c22edda0 100644 --- a/OnTopic/Obsolete/Mapping/Annotations/FollowAttribute.cs +++ b/OnTopic/Obsolete/Mapping/Annotations/FollowAttribute.cs @@ -23,7 +23,7 @@ public sealed class FollowAttribute : Attribute { /// /// The specific relationships that should be crawled. public FollowAttribute(Relationships relationships) { - Relationships = relationships; + Relationships = relationships; } /*============================================================================================================================ diff --git a/OnTopic/Obsolete/Mapping/Annotations/RelationshipAttribute.cs b/OnTopic/Obsolete/Mapping/Annotations/RelationshipAttribute.cs index 869a470b..ce324625 100644 --- a/OnTopic/Obsolete/Mapping/Annotations/RelationshipAttribute.cs +++ b/OnTopic/Obsolete/Mapping/Annotations/RelationshipAttribute.cs @@ -24,7 +24,7 @@ public sealed class RelationshipAttribute : Attribute { /// The key value of the collection associated with the current property. public RelationshipAttribute(string key) { TopicFactory.ValidateKey(key, false); - Key = key; + Key = key; } /// @@ -32,7 +32,7 @@ public RelationshipAttribute(string key) { /// /// Optional. The type of collection the collection is associated with. public RelationshipAttribute(RelationshipType type = RelationshipType.Any) { - Type = type; + Type = type; } /*============================================================================================================================ diff --git a/OnTopic/Obsolete/Metadata/Attributes/AttributeTypeDescriptor.cs b/OnTopic/Obsolete/Metadata/Attributes/AttributeTypeDescriptor.cs index bcb4a810..f07c8586 100644 --- a/OnTopic/Obsolete/Metadata/Attributes/AttributeTypeDescriptor.cs +++ b/OnTopic/Obsolete/Metadata/Attributes/AttributeTypeDescriptor.cs @@ -33,7 +33,7 @@ protected AttributeTypeDescriptor( string key, string contentType, Topic parent, - int id = -1 + int id = -1 ) : base( key, contentType, diff --git a/OnTopic/Obsolete/Repositories/DeleteEventArgs.cs b/OnTopic/Obsolete/Repositories/DeleteEventArgs.cs index 6ad527b8..a407181e 100644 --- a/OnTopic/Obsolete/Repositories/DeleteEventArgs.cs +++ b/OnTopic/Obsolete/Repositories/DeleteEventArgs.cs @@ -24,7 +24,7 @@ public class DeleteEventArgs : EventArgs { /// /// The topic. public DeleteEventArgs(Topic topic) : base() { - Topic = topic; + Topic = topic; } /*============================================================================================================================ diff --git a/OnTopic/Obsolete/Repositories/MoveEventArgs.cs b/OnTopic/Obsolete/Repositories/MoveEventArgs.cs index a5262b3a..db9c0bd3 100644 --- a/OnTopic/Obsolete/Repositories/MoveEventArgs.cs +++ b/OnTopic/Obsolete/Repositories/MoveEventArgs.cs @@ -43,8 +43,8 @@ public MoveEventArgs(Topic topic, Topic target) { Contract.Requires(topic, "topic"); Contract.Requires(target, "target"); Contract.Requires(topic != target, "The topic cannot be its own parent."); - Topic = topic; - Target = target; + Topic = topic; + Target = target; } /*============================================================================================================================ diff --git a/OnTopic/Obsolete/Repositories/RenameEventArgs.cs b/OnTopic/Obsolete/Repositories/RenameEventArgs.cs index c309efd8..00190fa0 100644 --- a/OnTopic/Obsolete/Repositories/RenameEventArgs.cs +++ b/OnTopic/Obsolete/Repositories/RenameEventArgs.cs @@ -25,7 +25,7 @@ public class RenameEventArgs : EventArgs { /// /// The topic object associated with the rename event. public RenameEventArgs(Topic topic) { - Topic = topic; + Topic = topic; } /*============================================================================================================================ diff --git a/OnTopic/Querying/TopicExtensions.cs b/OnTopic/Querying/TopicExtensions.cs index 088e37bd..bc068182 100644 --- a/OnTopic/Querying/TopicExtensions.cs +++ b/OnTopic/Querying/TopicExtensions.cs @@ -58,7 +58,7 @@ public static class TopicExtensions { \-------------------------------------------------------------------------------------------------------------------------*/ if (topic.IsLoaded(TopicPayload.Children)) { foreach (var child in topic.Children) { - var nestedResult = child.FindFirst(predicate); + var nestedResult = child.FindFirst(predicate); if (nestedResult is not null) { return nestedResult; } @@ -103,7 +103,7 @@ public static class TopicExtensions { if (predicate(topic.Parent)) { return topic.Parent; } - topic = topic.Parent; + topic = topic.Parent; } /*-------------------------------------------------------------------------------------------------------------------------- @@ -146,7 +146,7 @@ public static ReadOnlyTopicCollection FindAll(this Topic topic, Func + var contentTypeDescriptor = rootContentType?.FindFirst(t => t.Key.Equals(topic.ContentType, StringComparison.OrdinalIgnoreCase) && t is ContentTypeDescriptor ) as ContentTypeDescriptor; diff --git a/OnTopic/Repositories/ObservableTopicRepository.cs b/OnTopic/Repositories/ObservableTopicRepository.cs index 683d7ba5..80afb844 100644 --- a/OnTopic/Repositories/ObservableTopicRepository.cs +++ b/OnTopic/Repositories/ObservableTopicRepository.cs @@ -36,32 +36,32 @@ public abstract class ObservableTopicRepository : ITopicRepository { /// public event EventHandler? TopicLoaded { - add => _topicLoaded += value; - remove => _topicLoaded -= value; + add => _topicLoaded += value; + remove => _topicLoaded -= value; } /// public event EventHandler? TopicSaved { - add => _topicSaved += value; - remove => _topicSaved -= value; + add => _topicSaved += value; + remove => _topicSaved -= value; } /// public event EventHandler? TopicDeleted { - add => _topicDeleted += value; - remove => _topicDeleted -= value; + add => _topicDeleted += value; + remove => _topicDeleted -= value; } /// public event EventHandler? TopicMoved { - add => _topicMoved += value; - remove => _topicMoved -= value; + add => _topicMoved += value; + remove => _topicMoved -= value; } /// public event EventHandler? TopicRenamed { - add => _topicRenamed += value; - remove => _topicRenamed -= value; + add => _topicRenamed += value; + remove => _topicRenamed -= value; } #pragma warning disable CS0067 // Events are never used; retained as an obsolete stub which will be removed in the next major version diff --git a/OnTopic/Repositories/TopicRepository.cs b/OnTopic/Repositories/TopicRepository.cs index d3062a6a..b7952a1c 100644 --- a/OnTopic/Repositories/TopicRepository.cs +++ b/OnTopic/Repositories/TopicRepository.cs @@ -196,7 +196,7 @@ protected ContentTypeDescriptorCollection SetContentTypeDescriptors(ContentTypeD \-------------------------------------------------------------------------------------------------------------------------*/ var contentType = sourceTopic.ContentType; var contentTypes = GetContentTypeDescriptors(); - var contentTypeDescriptor = contentTypes.Contains(contentType)? contentTypes[contentType] : null; + var contentTypeDescriptor = contentTypes.Contains(contentType)? contentTypes[contentType] : null; if (contentTypeDescriptor is not null) { return contentTypeDescriptor; @@ -343,13 +343,13 @@ private async Task Save([NotNull]Topic topic, bool isRecursive, TopicCollection | Establish variables \-------------------------------------------------------------------------------------------------------------------------*/ var isNew = topic.IsNew; - var areRelationshipsDirty = topic.Relationships.IsDirty(); + var areRelationshipsDirty = topic.Relationships.IsDirty(); /*-------------------------------------------------------------------------------------------------------------------------- | Validate content type \-------------------------------------------------------------------------------------------------------------------------*/ - var contentTypeDescriptors= GetContentTypeDescriptors(); - var contentTypeDescriptor = GetContentTypeDescriptor(topic); + var contentTypeDescriptors = GetContentTypeDescriptors(); + var contentTypeDescriptor = GetContentTypeDescriptor(topic); if (contentTypeDescriptor is null) { throw new ReferentialIntegrityException( @@ -397,7 +397,7 @@ private async Task Save([NotNull]Topic topic, bool isRecursive, TopicCollection | Perform reordering and/or move \-------------------------------------------------------------------------------------------------------------------------*/ if (topic.Parent is not null && !topic.IsNew && topic.IsDirty("Parent")) { - var topicIndex = topic.Parent.Children.IndexOf(topic); + var topicIndex = topic.Parent.Children.IndexOf(topic); if (topicIndex > 0) { await Move(topic, topic.Parent, topic.Parent.Children[topicIndex - 1]).ConfigureAwait(false); } @@ -447,7 +447,7 @@ _contentTypeDescriptors is not null && /*-------------------------------------------------------------------------------------------------------------------------- | Reset original key \-------------------------------------------------------------------------------------------------------------------------*/ - topic.OriginalKey = null; + topic.OriginalKey = null; /*-------------------------------------------------------------------------------------------------------------------------- | Recurse over children @@ -681,7 +681,7 @@ public override sealed async Task Delete([ValidatedNotNull]Topic topic, bool isR /*-------------------------------------------------------------------------------------------------------------------------- | Raise event \-------------------------------------------------------------------------------------------------------------------------*/ - var args = new TopicEventArgs(topic); + var args = new TopicEventArgs(topic); OnTopicDeleted(args); } @@ -722,8 +722,8 @@ public override sealed async Task Delete([ValidatedNotNull]Topic topic, bool isR protected IEnumerable GetAttributes( Topic topic, bool? isExtendedAttribute, - bool? isDirty = null, - bool excludeLastModified = false + bool? isDirty = null, + bool excludeLastModified = false ) { /*-------------------------------------------------------------------------------------------------------------------------- diff --git a/OnTopic/Repositories/TopicRepositoryDecorator.cs b/OnTopic/Repositories/TopicRepositoryDecorator.cs index 5202c226..ce431aea 100644 --- a/OnTopic/Repositories/TopicRepositoryDecorator.cs +++ b/OnTopic/Repositories/TopicRepositoryDecorator.cs @@ -46,16 +46,16 @@ protected TopicRepositoryDecorator(ITopicRepository topicRepository) : base() { /*-------------------------------------------------------------------------------------------------------------------------- | Set values locally \-------------------------------------------------------------------------------------------------------------------------*/ - TopicRepository = topicRepository; + TopicRepository = topicRepository; /*-------------------------------------------------------------------------------------------------------------------------- | Subscribe to underlying events \-------------------------------------------------------------------------------------------------------------------------*/ - TopicRepository.TopicLoaded += (object? sender, TopicLoadEventArgs args) => OnTopicLoaded(args); - TopicRepository.TopicSaved += (object? sender, TopicSaveEventArgs args) => OnTopicSaved(args); - TopicRepository.TopicDeleted += (object? sender, TopicEventArgs args) => OnTopicDeleted(args); - TopicRepository.TopicMoved += (object? sender, TopicMoveEventArgs args) => OnTopicMoved(args); - TopicRepository.TopicRenamed += (object? sender, TopicRenameEventArgs args) => OnTopicRenamed(args); + TopicRepository.TopicLoaded += (object? sender, TopicLoadEventArgs args) => OnTopicLoaded(args); + TopicRepository.TopicSaved += (object? sender, TopicSaveEventArgs args) => OnTopicSaved(args); + TopicRepository.TopicDeleted += (object? sender, TopicEventArgs args) => OnTopicDeleted(args); + TopicRepository.TopicMoved += (object? sender, TopicMoveEventArgs args) => OnTopicMoved(args); + TopicRepository.TopicRenamed += (object? sender, TopicRenameEventArgs args) => OnTopicRenamed(args); } diff --git a/OnTopic/Topic.cs b/OnTopic/Topic.cs index 48d6a857..cce13b1f 100644 --- a/OnTopic/Topic.cs +++ b/OnTopic/Topic.cs @@ -118,9 +118,9 @@ public int Id { if (field > 0 && !field.Equals(value)) { throw new InvalidOperationException($"The value of this topic has already been set to {field}; it cannot be changed."); } - field = value; + field = value; } - } = -1; + } = -1; /*============================================================================================================================ | PROPERTY: PARENT @@ -255,7 +255,7 @@ public TopicPayload FilterPayload(TopicPayload payload) { continue; } if (IsLoaded(flag)) { - payload &= ~flag; + payload &= ~flag; } } @@ -361,7 +361,7 @@ public string Key { else if (_key is not null || IsNew) { _dirtyKeys.MarkDirty("Key"); } - _originalKey ??= _key; + _originalKey ??= _key; //If an established key value is changed, the parent's index must be manually updated; this won't happen automatically. if (_originalKey is not null && !value.Equals(_key, StringComparison.OrdinalIgnoreCase) && Parent is not null) { Parent._children.ChangeKey(this, value); @@ -395,7 +395,7 @@ internal string? OriginalKey { get => _originalKey; set { TopicFactory.ValidateKey(value, true); - _originalKey = value; + _originalKey = value; } } @@ -660,7 +660,7 @@ public void SetParent(Topic parent, Topic? sibling = null) { | Set parent values \-------------------------------------------------------------------------------------------------------------------------*/ if (_parent != parent) { - _parent = parent; + _parent = parent; } } @@ -682,13 +682,13 @@ public string GetUniqueKey() { /*-------------------------------------------------------------------------------------------------------------------------- | Crawl up tree to define uniqueKey \-------------------------------------------------------------------------------------------------------------------------*/ - var uniqueKey = ""; - var topic = (Topic?)this; + var uniqueKey = ""; + var topic = (Topic?)this; while (topic is not null) { if (uniqueKey.Length > 0) uniqueKey = $":{uniqueKey}"; - uniqueKey = topic.Key + uniqueKey; - topic = topic.Parent; + uniqueKey = topic.Key + uniqueKey; + topic = topic.Parent; } /*-------------------------------------------------------------------------------------------------------------------------- @@ -711,11 +711,11 @@ public string GetUniqueKey() { /// /// The HTTP-based path to the current . public string GetWebPath() { - var uniqueKey = GetUniqueKey() + var uniqueKey = GetUniqueKey() .Replace("Root:", "/", StringComparison.Ordinal) .Replace(":", "/", StringComparison.Ordinal) + "/"; if (!uniqueKey.StartsWith('/')) { - uniqueKey = $"/{uniqueKey}"; + uniqueKey = $"/{uniqueKey}"; } return uniqueKey; } From 6682c49fdbc8ae5f2042545754ab1864696fb884 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Wed, 8 Jul 2026 23:41:05 -0700 Subject: [PATCH 118/337] Ensured all files end on the last line --- .../TestDoubles/FakeControllerContext.cs | 2 +- OnTopic.AspNetCore.Mvc.Tests/TestDoubles/TestTopicRepository.cs | 2 +- OnTopic.Data.Sql/Properties/AssemblyInfo.cs | 2 +- OnTopic.Tests/Fixtures/TopicInfrastructureFixture.cs | 2 +- OnTopic.Tests/Fixtures/TypeAccessorFixture.cs | 2 +- OnTopic/Querying/TopicCollectionExtensions.cs | 2 +- 6 files changed, 6 insertions(+), 6 deletions(-) diff --git a/OnTopic.AspNetCore.Mvc.Tests/TestDoubles/FakeControllerContext.cs b/OnTopic.AspNetCore.Mvc.Tests/TestDoubles/FakeControllerContext.cs index 90344e4e..50469f03 100644 --- a/OnTopic.AspNetCore.Mvc.Tests/TestDoubles/FakeControllerContext.cs +++ b/OnTopic.AspNetCore.Mvc.Tests/TestDoubles/FakeControllerContext.cs @@ -57,4 +57,4 @@ public static ControllerContext GetControllerContext(string rootTopic, string? p } -} //Class +} //Class \ No newline at end of file diff --git a/OnTopic.AspNetCore.Mvc.Tests/TestDoubles/TestTopicRepository.cs b/OnTopic.AspNetCore.Mvc.Tests/TestDoubles/TestTopicRepository.cs index ed4038bb..18385ec0 100644 --- a/OnTopic.AspNetCore.Mvc.Tests/TestDoubles/TestTopicRepository.cs +++ b/OnTopic.AspNetCore.Mvc.Tests/TestDoubles/TestTopicRepository.cs @@ -124,4 +124,4 @@ private static Topic CreateFakeData() { } -} +} \ No newline at end of file diff --git a/OnTopic.Data.Sql/Properties/AssemblyInfo.cs b/OnTopic.Data.Sql/Properties/AssemblyInfo.cs index f3124e72..dc3570f8 100644 --- a/OnTopic.Data.Sql/Properties/AssemblyInfo.cs +++ b/OnTopic.Data.Sql/Properties/AssemblyInfo.cs @@ -26,4 +26,4 @@ [assembly: ComVisible(false)] [assembly: CLSCompliant(true)] [assembly: InternalsVisibleTo("OnTopic.Tests")] -[assembly: Guid("1de1f923-c7c2-435b-b49a-975acbcb5ff0")] +[assembly: Guid("1de1f923-c7c2-435b-b49a-975acbcb5ff0")] \ No newline at end of file diff --git a/OnTopic.Tests/Fixtures/TopicInfrastructureFixture.cs b/OnTopic.Tests/Fixtures/TopicInfrastructureFixture.cs index 1bdb80c8..d9bfbe65 100644 --- a/OnTopic.Tests/Fixtures/TopicInfrastructureFixture.cs +++ b/OnTopic.Tests/Fixtures/TopicInfrastructureFixture.cs @@ -82,4 +82,4 @@ public TopicInfrastructureFixture() { /// public ITopicMappingService MappingService { get; private set; } -} +} \ No newline at end of file diff --git a/OnTopic.Tests/Fixtures/TypeAccessorFixture.cs b/OnTopic.Tests/Fixtures/TypeAccessorFixture.cs index 80d294f5..1e75ad73 100644 --- a/OnTopic.Tests/Fixtures/TypeAccessorFixture.cs +++ b/OnTopic.Tests/Fixtures/TypeAccessorFixture.cs @@ -36,4 +36,4 @@ public TypeAccessorFixture() { /// internal TypeAccessor TypeAccessor { get; private set; } -} +} \ No newline at end of file diff --git a/OnTopic/Querying/TopicCollectionExtensions.cs b/OnTopic/Querying/TopicCollectionExtensions.cs index b930c608..8bcb01ab 100644 --- a/OnTopic/Querying/TopicCollectionExtensions.cs +++ b/OnTopic/Querying/TopicCollectionExtensions.cs @@ -43,4 +43,4 @@ public static class TopicCollectionExtensions { /// Returns true if any of the instances are . public static bool AnyNew(this IEnumerable topics) => topics.Any(t => t.IsNew); -} +} \ No newline at end of file From 6e8fb7dd4b45439b01412930f452fd75828aa50b Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Wed, 8 Jul 2026 23:54:27 -0700 Subject: [PATCH 119/337] Corrected XML docblock `cref` references This may just be a particularity of Jetbrains Rider, but it doesn't otherwise accept `cref` references unless the entire quoted identifier is on its own line. An irritating limitation, and especially because it can otherwise lead to awkward wrapping, but it is what it is. I just hope Visual Studio is cool with this, and it's not a mutual incompatibility. --- .../TopicViewLocationExpanderTest.cs | 4 +- .../TopicViewComponentTest.cs | 4 +- .../Components/MenuViewComponentBase{T}.cs | 8 +-- .../NavigationTopicViewComponentBase{T}.cs | 4 +- .../Controllers/ErrorController.cs | 4 +- .../Models/NavigationViewModel{T}.cs | 4 +- .../ServiceCollectionExtensions.cs | 4 +- .../_filters/TopicResponseCacheAttribute.cs | 4 +- OnTopic.Data.Caching/CachedTopicRepository.cs | 4 +- OnTopic.Tests/AttributeCollectionTest.cs | 12 ++-- ...lidNestedTopicListTypeTopicBindingModel.cs | 4 +- .../InvalidReferenceTypeTopicBindingModel.cs | 4 +- ...nvalidRelationshipTypeTopicBindingModel.cs | 4 +- OnTopic.Tests/ContentTypeDescriptorTest.cs | 4 +- OnTopic.Tests/ContractTest.cs | 4 +- .../Fixtures/TopicInfrastructureFixture.cs | 4 +- OnTopic.Tests/KeyedTopicCollectionTest.cs | 8 +-- OnTopic.Tests/MemberAccessorTest.cs | 26 ++++---- .../ReverseTopicMappingServiceTest.cs | 10 +-- .../DummyStaticTypeLookupService.cs | 4 +- OnTopic.Tests/TopicMappingServiceTest.cs | 16 ++--- OnTopic.Tests/TopicQueryingTest.cs | 4 +- OnTopic.Tests/TopicReferenceCollectionTest.cs | 64 +++++++++---------- .../TopicRelationshipMultiMapTest.cs | 40 ++++++------ OnTopic.Tests/TopicTest.cs | 16 ++--- OnTopic.Tests/TypeAccessorTest.cs | 42 ++++++------ OnTopic.Tests/TypeLookupServiceTest.cs | 8 +-- .../FilteredInvalidTopicViewModel.cs | 4 +- .../ViewModels/LoadTestingViewModel.cs | 4 +- .../AssociatedTopicBindingModel.cs | 4 +- .../BindingModels/RelatedTopicBindingModel.cs | 4 +- OnTopic/Associations/TopicReferenceRecord.cs | 6 +- .../Associations/TopicRelationshipMultiMap.cs | 4 +- OnTopic/Attributes/AttributeCollection.cs | 10 +-- OnTopic/Attributes/AttributeRecord.cs | 14 ++-- OnTopic/Attributes/AttributeValueConverter.cs | 4 +- .../Specialized/ReadOnlyTopicMultiMap.cs | 4 +- ...cordCollection{TItem,TValue,TAttribute}.cs | 38 +++++------ .../Specialized/TrackedRecord{T}.cs | 4 +- OnTopic/Internal/Reflection/ItemMetadata.cs | 8 +-- ...Dispatcher{TItem,TValue,TAttributeType}.cs | 12 ++-- OnTopic/Internal/Reflection/TypeAccessor.cs | 12 ++-- .../Mapping/Annotations/AssociationTypes.cs | 8 +-- .../Annotations/AttributeKeyAttribute.cs | 4 +- OnTopic/Mapping/CachedTopicMappingService.cs | 4 +- OnTopic/Mapping/Internal/AssociationMap.cs | 4 +- OnTopic/Mapping/Internal/ItemConfiguration.cs | 10 +-- .../Mapping/Internal/MappedTopicCacheEntry.cs | 8 +-- OnTopic/Mapping/TopicMappingService.cs | 4 +- .../Models/IAssociatedTopicBindingModel.cs | 4 +- OnTopic/Models/ITopicViewModel.cs | 8 +-- OnTopic/Obsolete/Attributes/AttributeValue.cs | 4 +- OnTopic/Querying/TopicCollectionExtensions.cs | 4 +- OnTopic/Repositories/ITopicRepository.cs | 12 ++-- OnTopic/Repositories/TopicRepository.cs | 20 +++--- .../_eventArgs/TopicSaveEventArgs.cs | 4 +- OnTopic/Topic.cs | 16 ++--- 57 files changed, 280 insertions(+), 280 deletions(-) diff --git a/OnTopic.AspNetCore.Mvc.IntegrationTests/TopicViewLocationExpanderTest.cs b/OnTopic.AspNetCore.Mvc.IntegrationTests/TopicViewLocationExpanderTest.cs index a21fff40..d1bfae24 100644 --- a/OnTopic.AspNetCore.Mvc.IntegrationTests/TopicViewLocationExpanderTest.cs +++ b/OnTopic.AspNetCore.Mvc.IntegrationTests/TopicViewLocationExpanderTest.cs @@ -37,8 +37,8 @@ public TopicViewLocationExpanderTest(WebApplicationFactory factory) { | TEST: EXPAND VIEW LOCATIONS: VIEWS \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Evaluates multiple views to ensure they fallback to the appropriate locations as defined in and . + /// Evaluates multiple views to ensure they fallback to the appropriate locations as defined in and . /// [Theory] [InlineData( "AreaContentTypeView", "ContentType/AreaContentTypeView.cshtml")] diff --git a/OnTopic.AspNetCore.Mvc.Tests/TopicViewComponentTest.cs b/OnTopic.AspNetCore.Mvc.Tests/TopicViewComponentTest.cs index 208d1cc0..3aa4471a 100644 --- a/OnTopic.AspNetCore.Mvc.Tests/TopicViewComponentTest.cs +++ b/OnTopic.AspNetCore.Mvc.Tests/TopicViewComponentTest.cs @@ -159,8 +159,8 @@ public async Task Menu_Invoke_ReturnsConfiguredNavigationRoot() { | TEST: NAVIGATION TOPIC VIEW MODEL: IS SELECTED: RETURNS EXPECTED OUTPUT \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Constructs a with a child instance, and ensures that the method returns the expected results. + /// Constructs a with a child instance, and ensures that the method returns the expected results. /// [Fact] public void NavigationTopicViewModel_IsSelected_ReturnsExpectedOutput() { diff --git a/OnTopic.AspNetCore.Mvc/Components/MenuViewComponentBase{T}.cs b/OnTopic.AspNetCore.Mvc/Components/MenuViewComponentBase{T}.cs index fe89f0c6..cc952877 100644 --- a/OnTopic.AspNetCore.Mvc/Components/MenuViewComponentBase{T}.cs +++ b/OnTopic.AspNetCore.Mvc/Components/MenuViewComponentBase{T}.cs @@ -31,10 +31,10 @@ namespace OnTopic.AspNetCore.Mvc.Components; /// abstract and suffixed with Base. /// /// -/// While the only requires that the implement , views will require additional properties. These can be determined on a per-case -/// basis, as required by the implementation. Implementaters, however, should consider implementing the interface, which provides the standard properties that most views will likely need, as +/// While the only requires that the implement , views will require additional properties. These can be determined on a per-case +/// basis, as required by the implementation. Implementaters, however, should consider implementing the interface, which provides the standard properties that most views will likely need, as /// well as a method for determining if the navigation item /// is currently selected. /// diff --git a/OnTopic.AspNetCore.Mvc/Components/NavigationTopicViewComponentBase{T}.cs b/OnTopic.AspNetCore.Mvc/Components/NavigationTopicViewComponentBase{T}.cs index 97c9ef39..92bfba64 100644 --- a/OnTopic.AspNetCore.Mvc/Components/NavigationTopicViewComponentBase{T}.cs +++ b/OnTopic.AspNetCore.Mvc/Components/NavigationTopicViewComponentBase{T}.cs @@ -67,8 +67,8 @@ IHierarchicalTopicMappingService hierarchicalTopicMappingService /// be mapped. /// /// - /// The associated with the . + /// The associated with the . /// protected IHierarchicalTopicMappingService HierarchicalTopicMappingService { get; } diff --git a/OnTopic.AspNetCore.Mvc/Controllers/ErrorController.cs b/OnTopic.AspNetCore.Mvc/Controllers/ErrorController.cs index eec76489..a3fda5b8 100644 --- a/OnTopic.AspNetCore.Mvc/Controllers/ErrorController.cs +++ b/OnTopic.AspNetCore.Mvc/Controllers/ErrorController.cs @@ -20,8 +20,8 @@ namespace OnTopic.AspNetCore.Mvc.Controllers; /// The will redirect to a URL with the /// HTTP error code in the route. This is fine if there is one error page that, perhaps, injects the error code into the /// content. It's also fine if there is an error page for every HTTP error. In practice, however, many sites handle some -/// HTTP errors, but not others. Given this, the provides logic to deliver a associated with the HTTP error, if available, and otherwise to fallback first to the +/// HTTP errors, but not others. Given this, the provides logic to deliver a associated with the HTTP error, if available, and otherwise to fallback first to the /// HTTP category (e.g., 5xx), and otherwise to a generic error. /// public class ErrorController : TopicController { diff --git a/OnTopic.AspNetCore.Mvc/Models/NavigationViewModel{T}.cs b/OnTopic.AspNetCore.Mvc/Models/NavigationViewModel{T}.cs index 1d34f9ca..5523ff3a 100644 --- a/OnTopic.AspNetCore.Mvc/Models/NavigationViewModel{T}.cs +++ b/OnTopic.AspNetCore.Mvc/Models/NavigationViewModel{T}.cs @@ -55,8 +55,8 @@ public class NavigationViewModel where T : class, IHierarchicalTopicViewModel /// /// /// In order to determine whether any given , the views - /// will need to know where in the hierarchy the user currently is. By storing this on the used as the root view model for every navigation component, we ensure that the views + /// will need to know where in the hierarchy the user currently is. By storing this on the used as the root view model for every navigation component, we ensure that the views /// always have access to this information. /// /// diff --git a/OnTopic.AspNetCore.Mvc/ServiceCollectionExtensions.cs b/OnTopic.AspNetCore.Mvc/ServiceCollectionExtensions.cs index c31f6613..f1679882 100644 --- a/OnTopic.AspNetCore.Mvc/ServiceCollectionExtensions.cs +++ b/OnTopic.AspNetCore.Mvc/ServiceCollectionExtensions.cs @@ -217,8 +217,8 @@ public static void MapImplicitAreaControllerRoute(this IEndpointRouteBuilder rou /// Adds the /Error/{errorCode} endpoint route for the . /// /// - /// This allows the to be used in conjunction with e.g., the , by providing a route for capturing the + /// This allows the to be used in conjunction with e.g., the , by providing a route for capturing the /// errorCode. /// /// The this route is being added to. diff --git a/OnTopic.AspNetCore.Mvc/_filters/TopicResponseCacheAttribute.cs b/OnTopic.AspNetCore.Mvc/_filters/TopicResponseCacheAttribute.cs index 8ba420f4..2f7254d3 100644 --- a/OnTopic.AspNetCore.Mvc/_filters/TopicResponseCacheAttribute.cs +++ b/OnTopic.AspNetCore.Mvc/_filters/TopicResponseCacheAttribute.cs @@ -25,8 +25,8 @@ namespace OnTopic.AspNetCore.Mvc; /// The Page content type has a topic reference to a CacheProfile content type, which contains settings for /// configuring HTTP response headers. The evaluates the current to /// determine which, if any, CacheProfile it is associated with, and applies the settings to the HTTP response -/// headers. If a CacheProfile is not configured, it will default to the CacheProfile with the of Default. +/// headers. If a CacheProfile is not configured, it will default to the CacheProfile with the of Default. /// /// /// This filter is enabled automatically when is diff --git a/OnTopic.Data.Caching/CachedTopicRepository.cs b/OnTopic.Data.Caching/CachedTopicRepository.cs index 37b3d09b..2f69a240 100644 --- a/OnTopic.Data.Caching/CachedTopicRepository.cs +++ b/OnTopic.Data.Caching/CachedTopicRepository.cs @@ -37,8 +37,8 @@ public class CachedTopicRepository : TopicRepositoryDecorator, ITopicLoadResolve | CONSTRUCTOR \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Instantiates a new instance of the with a dependency on an underlying in order to provide necessary data access. + /// Instantiates a new instance of the with a dependency on an underlying in order to provide necessary data access. /// /// /// A concrete instance of an , which will be used for data access. diff --git a/OnTopic.Tests/AttributeCollectionTest.cs b/OnTopic.Tests/AttributeCollectionTest.cs index 8df4c76b..f966441b 100644 --- a/OnTopic.Tests/AttributeCollectionTest.cs +++ b/OnTopic.Tests/AttributeCollectionTest.cs @@ -542,8 +542,8 @@ public void SetValue_ValueUnchanged_IsNotDirty() { | TEST: IS DIRTY: DIRTY VALUES: RETURNS TRUE \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Populates the with a that is marked as . Confirms that returns true. + /// Populates the with a that is marked as . Confirms that returns true. /// [Fact] public void IsDirty_DirtyValues_ReturnsTrue() { @@ -704,8 +704,8 @@ public void IsDirty_ExcludeLastModified_ReturnsFalse() { \---------------------------------------------------------------------------------------------------------------------------*/ /// /// Populates the with a and then deletes it. Confirms - /// that the returns the new version after calling . + /// that the returns the new version after calling . /// [Fact] public void IsDirty_MarkClean_UpdatesLastModified() { @@ -737,8 +737,8 @@ public void IsDirty_MarkClean_UpdatesLastModified() { \---------------------------------------------------------------------------------------------------------------------------*/ /// /// Populates the with a and then deletes it. Confirms - /// that returns false after calling . + /// that returns false after calling . /// [Fact] public void IsDirty_MarkClean_ReturnsFalse() { diff --git a/OnTopic.Tests/BindingModels/InvalidNestedTopicListTypeTopicBindingModel.cs b/OnTopic.Tests/BindingModels/InvalidNestedTopicListTypeTopicBindingModel.cs index 4f6c2660..b8ddc37e 100644 --- a/OnTopic.Tests/BindingModels/InvalidNestedTopicListTypeTopicBindingModel.cs +++ b/OnTopic.Tests/BindingModels/InvalidNestedTopicListTypeTopicBindingModel.cs @@ -12,8 +12,8 @@ namespace OnTopic.Tests.BindingModels; \-----------------------------------------------------------------------------------------------------------------------------*/ /// /// Provides a custom binding model with an invalid collection type—i.e., it implements a , even though nested topics are expected to return a type implementing . An should be thrown when it is mapped. +/// TValue}"/>, even though nested topics are expected to return a type implementing . An should be thrown when it is mapped. /// /// /// This is a sample class intended for test purposes only; it is not designed for use in a production environment. diff --git a/OnTopic.Tests/BindingModels/InvalidReferenceTypeTopicBindingModel.cs b/OnTopic.Tests/BindingModels/InvalidReferenceTypeTopicBindingModel.cs index 725bb867..392b92fc 100644 --- a/OnTopic.Tests/BindingModels/InvalidReferenceTypeTopicBindingModel.cs +++ b/OnTopic.Tests/BindingModels/InvalidReferenceTypeTopicBindingModel.cs @@ -12,8 +12,8 @@ namespace OnTopic.Tests.BindingModels; | BINDING MODEL: REFERENCE TYPE TOPIC (INVALID) \-----------------------------------------------------------------------------------------------------------------------------*/ /// -/// Provides a custom binding model with an invalid reference type—i.e., one that doesn't implement . An should be thrown when it is mapped. +/// Provides a custom binding model with an invalid reference type—i.e., one that doesn't implement . An should be thrown when it is mapped. /// /// /// This is a sample class intended for test purposes only; it is not designed for use in a production environment. diff --git a/OnTopic.Tests/BindingModels/InvalidRelationshipTypeTopicBindingModel.cs b/OnTopic.Tests/BindingModels/InvalidRelationshipTypeTopicBindingModel.cs index 2b414c8c..8ee6b253 100644 --- a/OnTopic.Tests/BindingModels/InvalidRelationshipTypeTopicBindingModel.cs +++ b/OnTopic.Tests/BindingModels/InvalidRelationshipTypeTopicBindingModel.cs @@ -11,8 +11,8 @@ namespace OnTopic.Tests.BindingModels; | BINDING MODEL: RELATIONSHIP TYPE TOPIC (INVALID) \-----------------------------------------------------------------------------------------------------------------------------*/ /// -/// Provides a custom binding model with an invalid —i.e., it refers to , even though the property is associated with a . +/// Provides a custom binding model with an invalid —i.e., it refers to , even though the property is associated with a . /// An should be thrown when it is mapped. /// /// diff --git a/OnTopic.Tests/ContentTypeDescriptorTest.cs b/OnTopic.Tests/ContentTypeDescriptorTest.cs index e44225d8..987613cf 100644 --- a/OnTopic.Tests/ContentTypeDescriptorTest.cs +++ b/OnTopic.Tests/ContentTypeDescriptorTest.cs @@ -13,8 +13,8 @@ namespace OnTopic.Tests; \-----------------------------------------------------------------------------------------------------------------------------*/ /// /// Provides unit tests for the class and other types associated with it, such as , , and . +/// cref="AttributeDescriptor"/>, , and . /// [ExcludeFromCodeCoverage] public class ContentTypeDescriptorTest { diff --git a/OnTopic.Tests/ContractTest.cs b/OnTopic.Tests/ContractTest.cs index 6a8c7e81..5be8e16f 100644 --- a/OnTopic.Tests/ContractTest.cs +++ b/OnTopic.Tests/ContractTest.cs @@ -88,8 +88,8 @@ public void Requires_MessageExists_ThrowExceptionWithMessage() { | TEST: REQUIRES: INVALID CONSTRUCTOR: THROW ARGUMENT EXCEPTION \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Tests a null argument using the class, and attempts to throw a custom with the expected , but fails due to no overload with + /// Tests a null argument using the class, and attempts to throw a custom with the expected , but fails due to no overload with /// a single message parameter. In this case, it should throw a . /// [Fact] diff --git a/OnTopic.Tests/Fixtures/TopicInfrastructureFixture.cs b/OnTopic.Tests/Fixtures/TopicInfrastructureFixture.cs index d9bfbe65..c3b260eb 100644 --- a/OnTopic.Tests/Fixtures/TopicInfrastructureFixture.cs +++ b/OnTopic.Tests/Fixtures/TopicInfrastructureFixture.cs @@ -17,8 +17,8 @@ namespace OnTopic.Tests.Fixtures; | CLASS: TOPIC INFRASTRUCTURE FIXTURE \-----------------------------------------------------------------------------------------------------------------------------*/ /// -/// Introduces a shared context to use for unit tests depending on an , , and, optionally, an . +/// Introduces a shared context to use for unit tests depending on an , , and, optionally, an . /// /// /// This basic fixture uses the , , - /// Attempts to add two instances with the same to a and confirms that a is correctly thrown. + /// Attempts to add two instances with the same to a and confirms that a is correctly thrown. /// [Fact] public void InsertItem_DuplicateKey_ThrowsException() => @@ -94,8 +94,8 @@ public void ReadOnlyKeyedTopicCollection_EmptyCollection() { \---------------------------------------------------------------------------------------------------------------------------*/ /// /// Establishes a with a backing and - /// confirms that it successfully returns a by using . + /// confirms that it successfully returns a by using . /// [Fact] public void ReadOnlyKeyedTopicCollection_GetValue_ReturnsValue() { diff --git a/OnTopic.Tests/MemberAccessorTest.cs b/OnTopic.Tests/MemberAccessorTest.cs index de25bfef..93ce19ae 100644 --- a/OnTopic.Tests/MemberAccessorTest.cs +++ b/OnTopic.Tests/MemberAccessorTest.cs @@ -158,8 +158,8 @@ public void IsSettable_ReadOnlyProperty_ReturnsFalse() { | TEST: GET VALUE: VALID PROPERTY: RETURNS VALUE \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Assembles a new from a , and attempts to call with a compliant object, expecting that the correct value will be returned. + /// Assembles a new from a , and attempts to call with a compliant object, expecting that the correct value will be returned. /// [Fact] public void GetValue_ValidProperty_ReturnsValue() { @@ -178,8 +178,8 @@ public void GetValue_ValidProperty_ReturnsValue() { | TEST: GET VALUE: VALID METHOD: RETURNS VALUE \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Assembles a new from a , and attempts to call with a compliant object, expecting that the correct value will be returned. + /// Assembles a new from a , and attempts to call with a compliant object, expecting that the correct value will be returned. /// [Theory] [InlineData(15)] @@ -203,8 +203,8 @@ public void GetValue_ValidMethod_ReturnsValue(int? value) { | TEST: GET VALUE: TYPE MISMATCH: THROWS EXCEPTION \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Assembles a new from a , and attempts to call with an object that doesn't contain the , expecting that an + /// Assembles a new from a , and attempts to call with an object that doesn't contain the , expecting that an /// will be thrown. /// [Fact] @@ -224,8 +224,8 @@ public void GetValue_TypeMismatch_ThrowsException() { | TEST: SET VALUE: VALID PROPERTY: SETS VALUE \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Assembles a new from a , and attempts to call with a compliant object, expecting that the correct value will be + /// Assembles a new from a , and attempts to call with a compliant object, expecting that the correct value will be /// set. /// [Theory] @@ -249,8 +249,8 @@ public void SetValue_ValidProperty_SetsValue(int? value) { | TEST: SET VALUE: VALID METHOD: SETS VALUE \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Assembles a new from a , and attempts to call with a compliant object, expecting that the correct value will be + /// Assembles a new from a , and attempts to call with a compliant object, expecting that the correct value will be /// set. /// [Theory] @@ -274,9 +274,9 @@ public void SetValue_ValidMethod_SetsValue(int? value) { | TEST: SET VALUE: MEMBER TYPE MISMATCH: THROWS EXCEPTION \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Assembles a new from a , and attempts to call with an object that isn't compatible with the , expecting that an will be thrown. + /// Assembles a new from a , and attempts to call with an object that isn't compatible with the , expecting that an will be thrown. /// [Fact] public void SetValue_MemberTypeMismatch_ThrowsException() { diff --git a/OnTopic.Tests/ReverseTopicMappingServiceTest.cs b/OnTopic.Tests/ReverseTopicMappingServiceTest.cs index cb31a6a0..6b352628 100644 --- a/OnTopic.Tests/ReverseTopicMappingServiceTest.cs +++ b/OnTopic.Tests/ReverseTopicMappingServiceTest.cs @@ -618,8 +618,8 @@ await _mappingService.MapAsync(bindingModel).ConfigureAwait(false) \---------------------------------------------------------------------------------------------------------------------------*/ /// /// Maps a content type that has a nested topic that implements an invalid collection type—i.e., it implements a , even though nestd topics are expected to return a type implementing . This is invalid, and expected to throw an . + /// cref="Dictionary{TKey, TValue}"/>, even though nestd topics are expected to return a type implementing . This is invalid, and expected to throw an . /// [Fact] public async Task Map_InvalidNestedTopicListType_ThrowsInvalidOperationException() { @@ -636,9 +636,9 @@ await _mappingService.MapAsync(bindingModel).ConfigureAwait(false) | TEST: MAP: INVALID TOPIC REFERENCE TYPE: THROWS INVALID OPERATION EXCEPTION \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Maps a content type that has a reference that implements an invalid type—i.e., it implements a , even though references are expected to return a type implementing . This is invalid, and expected to throw an . + /// Maps a content type that has a reference that implements an invalid type—i.e., it implements a , even though references are expected to return a type implementing . This is invalid, and expected to throw an . /// [Fact] public async Task Map_InvalidTopicReferenceType_ThrowsInvalidOperationException() { diff --git a/OnTopic.Tests/TestDoubles/DummyStaticTypeLookupService.cs b/OnTopic.Tests/TestDoubles/DummyStaticTypeLookupService.cs index 8e954991..6b40c823 100644 --- a/OnTopic.Tests/TestDoubles/DummyStaticTypeLookupService.cs +++ b/OnTopic.Tests/TestDoubles/DummyStaticTypeLookupService.cs @@ -21,8 +21,8 @@ public class DummyStaticTypeLookupService: StaticTypeLookupService { | CONSTRUCTOR \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Establishes a new instance of a . Optionally accepts a list of instances and a default value. + /// Establishes a new instance of a . Optionally accepts a list of instances and a default value. /// /// The list of instances to expose as part of this service. public DummyStaticTypeLookupService( diff --git a/OnTopic.Tests/TopicMappingServiceTest.cs b/OnTopic.Tests/TopicMappingServiceTest.cs index 85fc4208..4c761d5a 100644 --- a/OnTopic.Tests/TopicMappingServiceTest.cs +++ b/OnTopic.Tests/TopicMappingServiceTest.cs @@ -74,8 +74,8 @@ public TopicMappingServiceTest(TopicInfrastructureFixture f /// /// The includes functionality to map properties to attributes via a constructor that /// accepts a . This introduces some overhead which is not cost effective if there are - /// not any attributes that map to properties. For larger numbers of mapped attributes, however, the can reduce the mapping time considerably, while also giving more control over the model + /// not any attributes that map to properties. For larger numbers of mapped attributes, however, the can reduce the mapping time considerably, while also giving more control over the model /// construction to the model developer. This test is intended to help identify and optimize that threshold based on /// improvements to the underlying , , and convenience method. @@ -588,8 +588,8 @@ public async Task Map_AlternateAttributeKey_ReturnsMappedModel() { | TEST: MAPPED TOPIC CACHE: TRY GET VALUE: RETURNS ENTRY \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Establishes a and then confirms that it is returned via . + /// Establishes a and then confirms that it is returned via . /// [Fact] public void MappedTopicCache_TryGetValue_ReturnsEntry() { @@ -1566,8 +1566,8 @@ public async Task Map_FilterByContentType_ReturnsFilteredCollection() { | TEST: MAP: FLATTEN ATTRIBUTE: RETURNS FLAT COLLECTION \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Establishes a and tests whether the resulting object's property is properly flattened. + /// Establishes a and tests whether the resulting object's property is properly flattened. /// [Fact] public async Task Map_FlattenAttribute_ReturnsFlatCollection() { @@ -1591,8 +1591,8 @@ public async Task Map_FlattenAttribute_ReturnsFlatCollection() { | TEST: MAP: FLATTEN ATTRIBUTE: EXCLUDE TOPICS \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Establishes a and tests whether the resulting object's property excludes any or nested topics. + /// Establishes a and tests whether the resulting object's property excludes any or nested topics. /// [Fact] public async Task Map_FlattenAttribute_ExcludeTopics() { diff --git a/OnTopic.Tests/TopicQueryingTest.cs b/OnTopic.Tests/TopicQueryingTest.cs index 88bc09ae..73ecbccf 100644 --- a/OnTopic.Tests/TopicQueryingTest.cs +++ b/OnTopic.Tests/TopicQueryingTest.cs @@ -262,8 +262,8 @@ public async Task GetContentType_InvalidContentType_ReturnsNull() { /// /> returns null. /// /// - /// This varies from in that it returns a valid which doesn't derive from . + /// This varies from in that it returns a valid which doesn't derive from . /// [Fact] public async Task GetContentType_InvalidType_ReturnsNull() { diff --git a/OnTopic.Tests/TopicReferenceCollectionTest.cs b/OnTopic.Tests/TopicReferenceCollectionTest.cs index 4a0ac88b..70cef0eb 100644 --- a/OnTopic.Tests/TopicReferenceCollectionTest.cs +++ b/OnTopic.Tests/TopicReferenceCollectionTest.cs @@ -17,8 +17,8 @@ namespace OnTopic.Tests; /// Provides unit tests for the , with a particular emphasis on the custom features /// such as , , , and the cross-referencing of reciprocal values in the property. +/// SetValue(String, TValue, Boolean?, DateTime?)"/>, and the cross-referencing of reciprocal values in the property. /// [ExcludeFromCodeCoverage] public class TopicReferenceCollectionTest { @@ -47,8 +47,8 @@ public void Add_NewReference_IsDirty() { | TEST: SET VALUE: NEW REFERENCE: NOT DIRTY \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Assembles a new , adds a new reference using , and confirms that + /// Assembles a new , adds a new reference using , and confirms that /// is not set. /// [Fact] @@ -69,8 +69,8 @@ public void SetValue_NewReference_NotDirty() { \---------------------------------------------------------------------------------------------------------------------------*/ /// /// Assembles a new with a topic reference, removes that reference using , and confirms that is set. + /// "TrackedRecordCollection{TItem, TValue, TAttribute}.RemoveItem(Int32)"/>, and confirms that is set. /// [Fact] public void Remove_ExistingReference_IsDirty() { @@ -90,10 +90,10 @@ public void Remove_ExistingReference_IsDirty() { | TEST: CLEAR: EXISTING REFERENCES: IS DIRTY \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Assembles a new , adds a new reference using , calls and confirms that is set. Also confirms that items are correctly removed + /// Assembles a new , adds a new reference using , calls and confirms that is set. Also confirms that items are correctly removed /// from recipricol . /// [Fact] @@ -116,8 +116,8 @@ public void Clear_ExistingReferences_IsDirty() { | TEST: ADD: NEW TOPIC: IS DIRTY \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Assembles a new and adds a new reference using with set to false + /// Assembles a new and adds a new reference using with set to false /// , confirming that remains true /// since the target is unsaved. /// @@ -137,8 +137,8 @@ public void Add_NewTopic_IsDirty() { | TEST: ADD: NEW REFERENCE: INCOMING RELATIONSHIP SET \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Assembles a new , adds a new reference using , and confirms that + /// Assembles a new , adds a new reference using , and confirms that /// reference is correctly set. /// [Fact] @@ -157,14 +157,14 @@ public void Add_NewReference_IncomingRelationshipSet() { | TEST: REMOVE: EXISTING REFERENCE: INCOMING RELATIONSHIP REMOVED \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Assembles a new , adds a new reference using , removes the + /// Assembles a new , adds a new reference using , removes the /// reference using , and confirms that /// the reference is correctly removed as well. /// /// - /// This calls twice. The first to confirm that the is removed, the second to ensure that the attempt to call twice. The first to confirm that the is removed, the second to ensure that the attempt to call isn't disrupted by the fact that the is null. /// [Fact] @@ -187,8 +187,8 @@ public void Remove_ExistingReference_IncomingRelationshipRemoved() { | TEST: SET VALUE: EXISTING REFERENCE: TOPIC UPDATED \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Assembles a new , adds a new reference using , updates the + /// Assembles a new , adds a new reference using , updates the /// reference using , and confirms that the reference and are /// correctly updated. @@ -213,8 +213,8 @@ public void SetValue_ExistingReference_TopicUpdated() { | TEST: SET VALUE: NULL REFERENCE: TOPIC UPDATED \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Assembles a new , adds a new reference using , updates the + /// Assembles a new , adds a new reference using , updates the /// reference using with a null value, and confirms that the reference and are correctly removed. @@ -222,8 +222,8 @@ public void SetValue_ExistingReference_TopicUpdated() { /// /// This calls twice. The first to confirm that the is set, the second to ensure that - /// the attempt to call isn't disrupted by the fact that the will now be null. + /// the attempt to call isn't disrupted by the fact that the will now be null. /// [Fact] public void SetValue_ExistingReference_IncomingRelationshipsUpdates() { @@ -245,8 +245,8 @@ public void SetValue_ExistingReference_IncomingRelationshipsUpdates() { | TEST: SET VALUE: NULL REFERENCE: TOPIC REMOVED \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Assembles a new , adds a new reference using , updates the + /// Assembles a new , adds a new reference using , updates the /// reference with a null value using , and confirms that the reference is correctly removed. /// @@ -328,8 +328,8 @@ public void GetTopic_MissingReference_ReturnsNull() { | TEST: GET TOPIC: INHERITED REFERENCE: RETURNS TOPIC \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Assembles a new with a , adds a new reference to the , and confirms that with a , adds a new reference to the , and confirms that correctly returns the related topic reference, inheriting from both /// and . /// @@ -352,8 +352,8 @@ public void GetTopic_InheritedReference_ReturnsTopic() { | TEST: GET TOPIC: INHERITED REFERENCE: RETURNS NULL \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Assembles a new with a , adds a new reference to the , and confirms that with a , adds a new reference to the , and confirms that correctly returns null if an incorrect referencedKey is /// entered. /// @@ -375,8 +375,8 @@ public void GetTopic_InheritedReference_ReturnsNull() { | TEST: GET TOPIC: INHERITED REFERENCE WITHOUT INHERITANCE: RETURNS NULL \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Assembles a new with a , adds a new reference to the , and confirms that with a , adds a new reference to the , and confirms that correctly returns null if inheritFromBase is set to /// false. /// diff --git a/OnTopic.Tests/TopicRelationshipMultiMapTest.cs b/OnTopic.Tests/TopicRelationshipMultiMapTest.cs index 7af10b9d..5aa52a67 100644 --- a/OnTopic.Tests/TopicRelationshipMultiMapTest.cs +++ b/OnTopic.Tests/TopicRelationshipMultiMapTest.cs @@ -200,8 +200,8 @@ public void SetValue_UpdatesKeyCount() { | TEST: GET ENUMERATOR: RETURNS KEY/VALUES PAIRS \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Enumerates over the , ensuring that the enumerator defined by the interface implementation successfully relays the call to the underlying + /// Enumerates over the , ensuring that the enumerator defined by the interface implementation successfully relays the call to the underlying /// . /// [Fact] @@ -275,8 +275,8 @@ public void GetAllValues_ReturnsAllTopics() { | TEST: GET ALL VALUES: CONTENT TYPES: RETURNS ALL CONTENT TYPES \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Sets relationships in multiple namespaces, with different ContentTypes, then filters the results of by content type. + /// Sets relationships in multiple namespaces, with different ContentTypes, then filters the results of by content type. /// [Fact] public void GetAllValues_ContentTypes_ReturnsAllContentTypes() { @@ -317,8 +317,8 @@ public void SetTopic_IsDirty() { | TEST: SET VALUE: IS DUPLICATE: IS NOT DIRTY \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Adds a duplicate topic to a and confirms that value of is false. + /// Adds a duplicate topic to a and confirms that value of is false. /// [Fact] public void SetValue_IsDuplicate_IsNotDirty() { @@ -340,8 +340,8 @@ public void SetValue_IsDuplicate_IsNotDirty() { | TEST: SET VALUE: IS DUPLICATE: STAYS DIRTY \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Adds a duplicate topic to a and confirms that value of is false. + /// Adds a duplicate topic to a and confirms that value of is false. /// [Fact] public void SetSetValue_IsDuplicate_StaysDirty() { @@ -429,8 +429,8 @@ public void Remove_MissingTopic_StaysDirty() { | TEST: CLEAR: EXISTING TOPICS: IS DIRTY \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Call and confirms that value of is true. + /// Call and confirms that value of is true. /// [Fact] public void Clear_ExistingTopics_IsDirty() { @@ -470,8 +470,8 @@ public void Clear_NoTopics_IsNotDirty() { | TEST: SET VALUE: MARK NOT DIRTY: IS NOT DIRTY \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Adds an existing to a and confirms that returns false if to a and confirms that returns false if is called with the markDirty parameter set to false. /// [Fact] @@ -513,9 +513,9 @@ public void SetValue_NewParent_IsDirty() { | TEST: SET VALUE: NEW TOPIC: IS DIRTY \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Adds a new to a associated with an existing and confirms that returns true even if is called with the markDirty parameter + /// Adds a new to a associated with an existing and confirms that returns true even if is called with the markDirty parameter /// set to false. /// [Fact] @@ -536,8 +536,8 @@ public void SetValue_NewTopic_IsDirty() { \---------------------------------------------------------------------------------------------------------------------------*/ /// /// Adds an to a associated with a . - /// Confirms that returns false after calling . + /// Confirms that returns false after calling . /// [Fact] public void IsDirty_MarkClean_ReturnsFalse() { @@ -585,9 +585,9 @@ public void IsDirty_MarkClean_ReturnsTrue() { \---------------------------------------------------------------------------------------------------------------------------*/ /// /// Adds an to a associated with a . - /// Confirms that returns true even after calling if any of the s in the are marked as . + /// Confirms that returns true even after calling if any of the s in the are marked as . /// [Fact] public void IsDirty_MarkCleanWithNewTopic_ReturnsTrue() { diff --git a/OnTopic.Tests/TopicTest.cs b/OnTopic.Tests/TopicTest.cs index 1f4d8cc5..22698603 100644 --- a/OnTopic.Tests/TopicTest.cs +++ b/OnTopic.Tests/TopicTest.cs @@ -57,8 +57,8 @@ public void Create_ContentType_ReturnsDerivedTopic() { /// /// /// This is a special use case to address the fact that we expect concrete types of to - /// be in external plugin libraries, but the only needs to know that they're an . This is similar to how other types will fallback to if no matching type + /// be in external plugin libraries, but the only needs to know that they're an . This is similar to how other types will fallback to if no matching type /// can be found in the . /// [Fact] @@ -93,8 +93,8 @@ public void Id_ChangeValue_ThrowsArgumentException() { /// collection is updated to reflect the new . /// /// - /// By default, won't automatically update its key if the underlying changed. We have code that will handle that, however. + /// By default, won't automatically update its key if the underlying changed. We have code that will handle that, however. /// [Fact] public void Key_ChangeValue_UpdatesParent() { @@ -135,8 +135,8 @@ public void Parent_SetValue_UpdatesParent() { | TEST: PARENT: SET TO DESCENDANT: THROWS EXCEPTION \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Sets the to a that is a descendant, and ensure it throws an . + /// Sets the to a that is a descendant, and ensure it throws an . /// [Fact] public void Parent_SetToDescendant_ThrowsException() { @@ -418,8 +418,8 @@ public void IsDirty_ChangeKey_ReturnsTrue() => | TEST: IS DIRTY: EXISTING VALUES: REMAINS CLEAN \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Creates an existing topic, and updates the , , and to their existing values. Ensures that remains false. + /// Creates an existing topic, and updates the , , and to their existing values. Ensures that remains false. /// [Fact] public void IsDirty_ExistingValue_RemainsClean() { diff --git a/OnTopic.Tests/TypeAccessorTest.cs b/OnTopic.Tests/TypeAccessorTest.cs index 01d57e62..69fceee1 100644 --- a/OnTopic.Tests/TypeAccessorTest.cs +++ b/OnTopic.Tests/TypeAccessorTest.cs @@ -348,8 +348,8 @@ public void SetValue_Names_SetsResults() { | TEST: SET PROPERTY VALUE: KEY: SETS VALUE \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Establishes a and confirms that a key value can be properly set using the method. + /// Establishes a and confirms that a key value can be properly set using the method. /// [Fact] public void SetPropertyValue_Key_SetsValue() { @@ -392,8 +392,8 @@ public void SetPropertyValue_NullValue_SetsToNull() { \---------------------------------------------------------------------------------------------------------------------------*/ /// /// Establishes a and confirms that the sets the target property value to null if the value is set to . + /// String, Object?, Boolean)"/> sets the target property value to null if the value is set to . /// [Fact] public void SetPropertyValue_EmptyValue_SetsToNull() { @@ -452,8 +452,8 @@ public void SetPropertyValue_Boolean_SetsValue() { | TEST: SET PROPERTY VALUE: DATE/TIME: SETS VALUE \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Establishes a and confirms that a date/time value can be properly set using the method. + /// Establishes a and confirms that a date/time value can be properly set using the method. /// [Fact] public void SetPropertyValue_DateTime_SetsValue() { @@ -476,8 +476,8 @@ public void SetPropertyValue_DateTime_SetsValue() { | TEST: SET PROPERTY VALUE: INVALID PROPERTY: THROWS EXCEPTION \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Establishes a and confirms that an invalid property being set via the method throws an and confirms that an invalid property being set via the method throws an . /// [Fact] @@ -495,8 +495,8 @@ public void SetPropertyValue_InvalidProperty_ReturnsFalse() { | TEST: SET METHOD VALUE: VALID VALUE: SETS VALUE \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Establishes a and confirms that a value can be properly set using the method. + /// Establishes a and confirms that a value can be properly set using the method. /// [Fact] public void SetMethodValue_ValidValue_SetsValue() { @@ -513,8 +513,8 @@ public void SetMethodValue_ValidValue_SetsValue() { | TEST: SET METHOD VALUE: INVALID VALUE: DOESN'T SET VALUE \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Establishes a and confirms that a value set with an invalid value using the method returns false. + /// Establishes a and confirms that a value set with an invalid value using the method returns false. /// [Fact] public void SetMethodValue_InvalidValue_DoesNotSetValue() { @@ -532,8 +532,8 @@ public void SetMethodValue_InvalidValue_DoesNotSetValue() { | TEST: SET METHOD VALUE: INVALID MEMBER: THROWS EXCEPTION \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Establishes a and confirms that setting an invalid method name using the method throws an exception. + /// Establishes a and confirms that setting an invalid method name using the method throws an exception. /// [Fact] public void SetMethodValue_InvalidMember_ThrowsException() { @@ -570,9 +570,9 @@ public void SetMethodValue_ValidReferenceValue_SetsValue() { | TEST: SET METHOD VALUE: INVALID REFERENCE VALUE: THROWS EXCEPTION \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Establishes a and confirms that a value set with an invalid value using the method throws an . + /// Establishes a and confirms that a value set with an invalid value using the method throws an . /// [Fact] public void SetMethodValue_InvalidReferenceValue_ThrowsException() { @@ -591,8 +591,8 @@ public void SetMethodValue_InvalidReferenceValue_ThrowsException() { | TEST: SET METHOD VALUE: INVALID REFERENCE MEMBER: THROWS EXCEPTION \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Establishes a and confirms that setting an invalid method name using the method returns false. + /// Establishes a and confirms that setting an invalid method name using the method returns false. /// [Fact] public void SetMethodValue_InvalidReferenceMember_ThrowsException() { @@ -610,8 +610,8 @@ public void SetMethodValue_InvalidReferenceMember_ThrowsException() { | TEST: SET METHOD VALUE: NULL REFERENCE VALUE: DOESN'T SET VALUE \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Establishes a and confirms that a value set with an null value using the method returns false. + /// Establishes a and confirms that a value set with an null value using the method returns false. /// [Fact] public void SetMethodValue_NullReferenceValue_DoesNotSetValue() { diff --git a/OnTopic.Tests/TypeLookupServiceTest.cs b/OnTopic.Tests/TypeLookupServiceTest.cs index ff59831a..3c4d3366 100644 --- a/OnTopic.Tests/TypeLookupServiceTest.cs +++ b/OnTopic.Tests/TypeLookupServiceTest.cs @@ -16,8 +16,8 @@ namespace OnTopic.Tests; | CLASS: TYPE LOOKUP SERVICE TEST \-----------------------------------------------------------------------------------------------------------------------------*/ /// -/// Provides unit tests for the interface and its implementations, such as the , , , +/// Provides unit tests for the interface and its implementations, such as the , , , /// and the underlying . /// [ExcludeFromCodeCoverage] @@ -104,8 +104,8 @@ public void StaticLookupService_AddOrReplace_ReturnsExpected() { | TEST: DYNAMIC TYPE LOOKUP SERVICE: PREDICATE: RETURNS EXPECTED \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Establishes a with a custom predicate and calls the underlying to ensure it correctly adds the expected items. + /// Establishes a with a custom predicate and calls the underlying to ensure it correctly adds the expected items. /// [Fact] public void DynamicTypeLookupService_Predicate_ReturnsExpected() { diff --git a/OnTopic.Tests/ViewModels/FilteredInvalidTopicViewModel.cs b/OnTopic.Tests/ViewModels/FilteredInvalidTopicViewModel.cs index 5eebe086..34d971a8 100644 --- a/OnTopic.Tests/ViewModels/FilteredInvalidTopicViewModel.cs +++ b/OnTopic.Tests/ViewModels/FilteredInvalidTopicViewModel.cs @@ -10,8 +10,8 @@ namespace OnTopic.Tests.ViewModels; | VIEW MODEL: FILTERED TOPIC (INVALID) \-----------------------------------------------------------------------------------------------------------------------------*/ /// -/// Provides a strongly-typed data transfer object for testing views properties annotated with the . Includes an invalid . +/// Provides a strongly-typed data transfer object for testing views properties annotated with the . Includes an invalid . /// /// /// This is a sample class intended for test purposes only; it is not designed for use in a production environment. diff --git a/OnTopic.Tests/ViewModels/LoadTestingViewModel.cs b/OnTopic.Tests/ViewModels/LoadTestingViewModel.cs index 38805228..82987bef 100644 --- a/OnTopic.Tests/ViewModels/LoadTestingViewModel.cs +++ b/OnTopic.Tests/ViewModels/LoadTestingViewModel.cs @@ -11,8 +11,8 @@ namespace OnTopic.Tests.ViewModels; | VIEW MODEL: LOAD TESTING \-----------------------------------------------------------------------------------------------------------------------------*/ /// -/// Provides a simple view model with a series of properties that can be used for load testing the . +/// Provides a simple view model with a series of properties that can be used for load testing the . /// /// /// This is a sample class intended for test purposes only; it is not designed for use in a production environment. diff --git a/OnTopic.ViewModels/BindingModels/AssociatedTopicBindingModel.cs b/OnTopic.ViewModels/BindingModels/AssociatedTopicBindingModel.cs index c82d8411..66391396 100644 --- a/OnTopic.ViewModels/BindingModels/AssociatedTopicBindingModel.cs +++ b/OnTopic.ViewModels/BindingModels/AssociatedTopicBindingModel.cs @@ -15,8 +15,8 @@ namespace OnTopic.ViewModels.BindingModels; /// /// /// While implementors may choose to create a custom implementation, the out-of- -/// the-box implementation satisfies all of the requirements of the . The only reason to implement a custom definition is if the caller needs additional +/// the-box implementation satisfies all of the requirements of the . The only reason to implement a custom definition is if the caller needs additional /// metadata for separate validation or processing. /// public record AssociatedTopicBindingModel : IAssociatedTopicBindingModel { diff --git a/OnTopic.ViewModels/BindingModels/RelatedTopicBindingModel.cs b/OnTopic.ViewModels/BindingModels/RelatedTopicBindingModel.cs index 6e0dca5a..08959a6f 100644 --- a/OnTopic.ViewModels/BindingModels/RelatedTopicBindingModel.cs +++ b/OnTopic.ViewModels/BindingModels/RelatedTopicBindingModel.cs @@ -15,8 +15,8 @@ namespace OnTopic.ViewModels.BindingModels; /// /// /// While implementors may choose to create a custom implementation, the out-of- -/// the-box implementation satisfies all of the requirements of the . The only reason to implement a custom definition is if the caller needs additional +/// the-box implementation satisfies all of the requirements of the . The only reason to implement a custom definition is if the caller needs additional /// metadata for separate validation or processing. /// [ExcludeFromCodeCoverage] diff --git a/OnTopic/Associations/TopicReferenceRecord.cs b/OnTopic/Associations/TopicReferenceRecord.cs index 37c41d50..db599f4b 100644 --- a/OnTopic/Associations/TopicReferenceRecord.cs +++ b/OnTopic/Associations/TopicReferenceRecord.cs @@ -17,9 +17,9 @@ namespace OnTopic.Associations; /// /// /// -/// Provides values and metadata specific to individual attribute values, such as state (e.g., the property signifies whether the attribute value has changed) and its date. +/// Provides values and metadata specific to individual attribute values, such as state (e.g., the property signifies whether the attribute value has changed) and its date. /// /// /// Typically, the will be exposed as part of a diff --git a/OnTopic/Associations/TopicRelationshipMultiMap.cs b/OnTopic/Associations/TopicRelationshipMultiMap.cs index 34613b41..f13e3baa 100644 --- a/OnTopic/Associations/TopicRelationshipMultiMap.cs +++ b/OnTopic/Associations/TopicRelationshipMultiMap.cs @@ -58,8 +58,8 @@ public TopicRelationshipMultiMap(Topic parent, bool isIncoming = false): base(ne /// Removes all objects grouped by a specific . /// /// - /// If there are any objects in the specified , then the will be marked as . + /// If there are any objects in the specified , then the will be marked as . /// /// The key of the relationship to be cleared. public void Clear(string relationshipKey) { diff --git a/OnTopic/Attributes/AttributeCollection.cs b/OnTopic/Attributes/AttributeCollection.cs index ae8b949e..821527e6 100644 --- a/OnTopic/Attributes/AttributeCollection.cs +++ b/OnTopic/Attributes/AttributeCollection.cs @@ -37,8 +37,8 @@ public class AttributeCollection : TrackedRecordCollection class. /// /// - /// The is intended exclusively for providing access to attributes via the property. For this reason, the constructor is marked as internal. + /// The is intended exclusively for providing access to attributes via the property. For this reason, the constructor is marked as internal. /// /// A reference to the topic that the current attribute collection is bound to. internal AttributeCollection(Topic parentTopic) : base(parentTopic) { @@ -187,9 +187,9 @@ public void SetValue( | METHOD: AS ATTRIBUTE DICTIONARY \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Gets an based on the of the current . Optionall includes attributes from any s that the derives from. + /// Gets an based on the of the current . Optionall includes attributes from any s that the derives from. /// /// /// The method will exclude attributes which correspond to properties on diff --git a/OnTopic/Attributes/AttributeRecord.cs b/OnTopic/Attributes/AttributeRecord.cs index 9899fa2f..aadc3bb1 100644 --- a/OnTopic/Attributes/AttributeRecord.cs +++ b/OnTopic/Attributes/AttributeRecord.cs @@ -17,9 +17,9 @@ namespace OnTopic.Attributes; /// /// /// -/// Provides values and metadata specific to individual attribute values, such as state (e.g., the property signifies whether the attribute value has changed) and its date. +/// Provides values and metadata specific to individual attribute values, such as state (e.g., the property signifies whether the attribute value has changed) and its date. /// /// /// Typically, the will be exposed as part of a via the @@ -27,8 +27,8 @@ namespace OnTopic.Attributes; /// /// /// Be aware that while represents the value of a specific attribute, the metadata for -/// describing the purpose, constraints, and usage of that particular attribute is described by the class. +/// describing the purpose, constraints, and usage of that particular attribute is described by the class. /// /// /// This class is immutable: once it is constructed, the values cannot be changed. To change a value, callers must either @@ -101,8 +101,8 @@ public AttributeRecord( /// cref="TrackedRecord{T}.IsDirty"/> to determine if a value should be saved. If an attribute's value hasn't changed, /// but the location it should be stored has, that could potentially result in the attribute being deleted, as the /// attribute won't show up for when is called with isDirty set to - /// true and isExtendedAttribute is set to either true or false. By introducing , the is able to detect conflicts between the configuration and + /// true and isExtendedAttribute is set to either true or false. By introducing , the is able to detect conflicts between the configuration and /// the underlying data store, and ensure data is stored appropriately. /// /// diff --git a/OnTopic/Attributes/AttributeValueConverter.cs b/OnTopic/Attributes/AttributeValueConverter.cs index 781288ab..2b5c8935 100644 --- a/OnTopic/Attributes/AttributeValueConverter.cs +++ b/OnTopic/Attributes/AttributeValueConverter.cs @@ -13,8 +13,8 @@ namespace OnTopic.Attributes; | CLASS: ATTRIBUTE VALUE CONVERTER \-----------------------------------------------------------------------------------------------------------------------------*/ /// -/// Attribute values are stored as strings, but may be deserialized to other value types using e.g. the or the . This class provides basic methods for +/// Attribute values are stored as strings, but may be deserialized to other value types using e.g. the or the . This class provides basic methods for /// converting from the string representation to supported value types. /// internal static class AttributeValueConverter { diff --git a/OnTopic/Collections/Specialized/ReadOnlyTopicMultiMap.cs b/OnTopic/Collections/Specialized/ReadOnlyTopicMultiMap.cs index 2f89ad0d..2872119f 100644 --- a/OnTopic/Collections/Specialized/ReadOnlyTopicMultiMap.cs +++ b/OnTopic/Collections/Specialized/ReadOnlyTopicMultiMap.cs @@ -37,8 +37,8 @@ public ReadOnlyTopicMultiMap(TopicMultiMap source) { /// /// /// The must be passed in via either the public - /// constructor, or must be set manually from the constructor of a derived class when using the protected constructor. + /// constructor, or must be set manually from the constructor of a derived class when using the protected constructor. /// [NotNull, DisallowNull] protected TopicMultiMap? Source { get; init; } diff --git a/OnTopic/Collections/Specialized/TrackedRecordCollection{TItem,TValue,TAttribute}.cs b/OnTopic/Collections/Specialized/TrackedRecordCollection{TItem,TValue,TAttribute}.cs index 398966ee..cd0120c7 100644 --- a/OnTopic/Collections/Specialized/TrackedRecordCollection{TItem,TValue,TAttribute}.cs +++ b/OnTopic/Collections/Specialized/TrackedRecordCollection{TItem,TValue,TAttribute}.cs @@ -17,8 +17,8 @@ namespace OnTopic.Collections.Specialized; /// working with their state. /// /// -/// records represent individual instances of values associated with a particular . The class tracks these through e.g. its property. The records represent individual instances of values associated with a particular . The class tracks these through e.g. its property. The class provides a base class with methods for working with /// these records, such as , for determining if a given record has been modified, or for creating or "updating" a record. (Records are @@ -74,12 +74,12 @@ internal TrackedRecordCollection(Topic parentTopic) : base(StringComparer.Ordina /// /// /// As a performance enhancement, implementations will only save topics that are marked as - /// . If a is deleted, then it won't be marked as . If no other instances were modified, then the won't get saved, and that won't be deleted. Further more, methods like + /// . If a is deleted, then it won't be marked as . If no other instances were modified, then the won't get saved, and that won't be deleted. Further more, methods like /// the method have no way of detecting the deletion of - /// arbitrary values�i.e., attributes that were deleted which don't correspond to attributes configured on the . By tracking any deleted instances, we ensure both + /// arbitrary values�i.e., attributes that were deleted which don't correspond to attributes configured on the . By tracking any deleted instances, we ensure both /// scenarios can be accounted for. /// internal List DeletedItems { get; } = new(); @@ -98,8 +98,8 @@ internal TrackedRecordCollection(Topic parentTopic) : base(StringComparer.Ordina /// /// This method is intended primarily for data storage providers, such as , which may need /// to determine the state of a prior to saving it - /// to the data storage medium. Because is a state of the current , it does not support inheritFromParent or inheritFromBase (which otherwise default + /// to the data storage medium. Because is a state of the current , it does not support inheritFromParent or inheritFromBase (which otherwise default /// to true). /// /// The string identifier for the . @@ -127,8 +127,8 @@ public bool IsDirty(string key) { /// /// /// This method is intended primarily for data storage providers, such as , so that they can - /// mark the collection, and all instances it contains, as clean. After this, method will return false until any instances are added, modified, + /// mark the collection, and all instances it contains, as clean. After this, method will return false until any instances are added, modified, /// or removed. /// /// @@ -325,8 +325,8 @@ ParentCollection is not null /// depending on whether that value already exists. /// /// - /// Working with records can be a bit cumbersome, and especially in determining if a value should be marked as , since that's based on a comparison with the previous value. The , since that's based on a comparison with the previous value. The method handles this logic for implementers, while simultaneously allowing /// callers to explicitly set whether the instances should be marked as dirty�via the /// parameter�and, optionally, what the should be. @@ -534,8 +534,8 @@ internal void SetValue( /// The location that the should be set. /// The object which is being inserted. /// - /// An is thrown if an with the same as the already exists. + /// An is thrown if an with the same as the already exists. /// protected override void InsertItem(int index, TItem item) { Contract.Requires(item, nameof(item)); @@ -618,8 +618,8 @@ protected override void RemoveItem(int index) { /// it is appropriately marked as . /// /// - /// In order to ensure any business logic is enforced, loops through every in the and explicitly calls loops through every in the and explicitly calls . This is slower, but ensures that any state tracking and null /// validation that occurs in the properties is maintained. Fortunately, this is a rare use case; we typically expect /// attributes to be handled individually. @@ -638,8 +638,8 @@ protected override void ClearItems() { /// Determines if a is permitted to be marked as not . /// /// - /// If the is or the is and the is , then + /// If the is or the is and the is , then /// should never be set to false. /// /// The object which is being inserted. diff --git a/OnTopic/Collections/Specialized/TrackedRecord{T}.cs b/OnTopic/Collections/Specialized/TrackedRecord{T}.cs index b1758a3a..0c3f8f37 100644 --- a/OnTopic/Collections/Specialized/TrackedRecord{T}.cs +++ b/OnTopic/Collections/Specialized/TrackedRecord{T}.cs @@ -16,8 +16,8 @@ namespace OnTopic.Collections.Specialized; /// /// The class is comparable to the , in that it tracks the and for an item, but it additionally provides metadata related to the record, including -/// the and whether or not it . This makes it easier for e.g. implementations to make more informed decisions about whether a record needs to be saved or +/// the and whether or not it . This makes it easier for e.g. implementations to make more informed decisions about whether a record needs to be saved or /// overwritten during a or . /// public abstract record TrackedRecord { diff --git a/OnTopic/Internal/Reflection/ItemMetadata.cs b/OnTopic/Internal/Reflection/ItemMetadata.cs index 57d80a0b..e0beaff5 100644 --- a/OnTopic/Internal/Reflection/ItemMetadata.cs +++ b/OnTopic/Internal/Reflection/ItemMetadata.cs @@ -82,8 +82,8 @@ internal ItemMetadata(string name, ICustomAttributeProvider attributeProvider) /// property is provided with an initter, which will automatically set , , and when it is set. If this is not done properly, dependency classes will /// not work properly, and will likely fail. Since there are only two expected derived classes— and —this shouldn't be a problem. To help avoid this scenario, a is thrown with instructions in the unexpected case that is not set. + /// /> and —this shouldn't be a problem. To help avoid this scenario, a is thrown with instructions in the unexpected case that is not set. /// public Type Type { get { @@ -136,8 +136,8 @@ internal ItemConfiguration Configuration { | IS LIST? \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Determine if the member is a , , , or . + /// Determine if the member is a , , , or . /// internal bool IsList { get; init; } diff --git a/OnTopic/Internal/Reflection/TopicPropertyDispatcher{TItem,TValue,TAttributeType}.cs b/OnTopic/Internal/Reflection/TopicPropertyDispatcher{TItem,TValue,TAttributeType}.cs index c8b387df..4622ba65 100644 --- a/OnTopic/Internal/Reflection/TopicPropertyDispatcher{TItem,TValue,TAttributeType}.cs +++ b/OnTopic/Internal/Reflection/TopicPropertyDispatcher{TItem,TValue,TAttributeType}.cs @@ -53,8 +53,8 @@ namespace OnTopic.Internal.Reflection; /// "/>. As such, by saving a reference to those as part of the process, we allow /// the source collection to retrieve the original request in order to ensure that data isn't lost. This isn't as critical /// for e.g. since the will be the same -/// that's sent to the corresponding property, and thus is expected to be the same as the value set by the property itself. +/// that's sent to the corresponding property, and thus is expected to be the same as the value set by the property itself. /// /// /// In a typical workflow, the method will end up getting once or twice. The first @@ -69,8 +69,8 @@ namespace OnTopic.Internal.Reflection; /// One caveat to this are cases where the caller attempts to set the value via the property directly, /// instead of adding the item directly to the corresponding collection—e.g., they call instead /// of e.g. the method from -/// . In that case, the business logic will already have been enforced, but the method will not have been called. To mitigate the property setter getting called twice, +/// . In that case, the business logic will already have been enforced, but the method will not have been called. To mitigate the property setter getting called twice, /// collection implementors are advised to offer an internal overload that allows an item to be added to the collection /// while bypassing the business logic. For instance, this can be done using or . /// /// - /// It's worth noting that any calls to are invalidated the next time is called. As such, is not a way to permanently + /// It's worth noting that any calls to are invalidated the next time is called. As such, is not a way to permanently /// disable calling a property setter. (The correct way to do that is to remove the property setter, or at least its /// corresponding .) Instead, it only disables the next attempt to add an item /// corresponding to that key—which, if correctly implemented, will be when the current diff --git a/OnTopic/Internal/Reflection/TypeAccessor.cs b/OnTopic/Internal/Reflection/TypeAccessor.cs index f506d72d..8f5d5511 100644 --- a/OnTopic/Internal/Reflection/TypeAccessor.cs +++ b/OnTopic/Internal/Reflection/TypeAccessor.cs @@ -24,13 +24,13 @@ namespace OnTopic.Internal.Reflection; /// For setting values, the typical workflow is for a caller to check either or , followed by or to retrieve the value. In these -/// scenarios, the will attempt to deserialize the value parameter from to the type expected by the corresponding property or method. Typically, this will be a , +/// scenarios, the will attempt to deserialize the value parameter from to the type expected by the corresponding property or method. Typically, this will be a , /// , , or . /// /// -/// Alternatively, setters can call or , in which case the final value parameter will be set the +/// Alternatively, setters can call or , in which case the final value parameter will be set the /// target property, or passed as the parameter of the method without any attempt to convert it. Obviously, this requires /// that the target type be assignable from the value object. /// @@ -365,8 +365,8 @@ internal void SetValue(object target, string memberName, object? value, bool all | METHOD: SET PROPERTY VALUE \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Uses reflection to call a property, assuming that it is a) writable, and b) of type , , or , or is otherwise compatible with the type. + /// Uses reflection to call a property, assuming that it is a) writable, and b) of type , , or , or is otherwise compatible with the type. /// /// The object on which the property is defined. /// The name of the property to set, derived from . diff --git a/OnTopic/Mapping/Annotations/AssociationTypes.cs b/OnTopic/Mapping/Annotations/AssociationTypes.cs index 1283a517..ae355ddc 100644 --- a/OnTopic/Mapping/Annotations/AssociationTypes.cs +++ b/OnTopic/Mapping/Annotations/AssociationTypes.cs @@ -17,8 +17,8 @@ namespace OnTopic.Mapping.Annotations; /// /// The and use the enum to /// determine what associations should be mapped—or followed—as part of the mapping process. This helps constrain the -/// scope of the object graph to only include the data needed for a given view, or vice verse. That said, the enum can be used any place where the code needs to model multiple types of associations relevant +/// scope of the object graph to only include the data needed for a given view, or vice verse. That said, the enum can be used any place where the code needs to model multiple types of associations relevant /// to the class and its view models. /// /// @@ -91,8 +91,8 @@ public enum AssociationTypes { /// Map topic pointer references, such as . /// /// - /// By convention, types refer to a , , or property identifier ending in Id. + /// By convention, types refer to a , , or property identifier ending in Id. /// References = 1 << 5, diff --git a/OnTopic/Mapping/Annotations/AttributeKeyAttribute.cs b/OnTopic/Mapping/Annotations/AttributeKeyAttribute.cs index f25c197c..1e08426d 100644 --- a/OnTopic/Mapping/Annotations/AttributeKeyAttribute.cs +++ b/OnTopic/Mapping/Annotations/AttributeKeyAttribute.cs @@ -11,8 +11,8 @@ namespace OnTopic.Mapping.Annotations; | ATTRIBUTE: ATTRIBUTE KEY \-----------------------------------------------------------------------------------------------------------------------------*/ /// -/// Flags that a property should be mapped to a specific attributeKey in when calling . +/// Flags that a property should be mapped to a specific attributeKey in when calling . /// /// /// By default, implementations will attempt to map the property of the target data diff --git a/OnTopic/Mapping/CachedTopicMappingService.cs b/OnTopic/Mapping/CachedTopicMappingService.cs index 6f6f56f4..7250416c 100644 --- a/OnTopic/Mapping/CachedTopicMappingService.cs +++ b/OnTopic/Mapping/CachedTopicMappingService.cs @@ -160,8 +160,8 @@ public class CachedTopicMappingService(ITopicMappingService topicMappingService) /// The internal will potentially add two entries to the cache for every view model. /// /// - /// The first will be bound to the , view model , and the mapped. + /// The first will be bound to the , view model , and the mapped. /// /// /// The second will assume a null , and can be used for scenarios where the is diff --git a/OnTopic/Mapping/Internal/AssociationMap.cs b/OnTopic/Mapping/Internal/AssociationMap.cs index a2459359..9b15362a 100644 --- a/OnTopic/Mapping/Internal/AssociationMap.cs +++ b/OnTopic/Mapping/Internal/AssociationMap.cs @@ -16,8 +16,8 @@ namespace OnTopic.Mapping.Internal; /// /// /// While the and enumerations are distinct, there are times -/// when a single needs to be related to an item in the collection of . This mapping makes that feasible. +/// when a single needs to be related to an item in the collection of . This mapping makes that feasible. /// static internal class AssociationMap { diff --git a/OnTopic/Mapping/Internal/ItemConfiguration.cs b/OnTopic/Mapping/Internal/ItemConfiguration.cs index 8d706932..928ac588 100644 --- a/OnTopic/Mapping/Internal/ItemConfiguration.cs +++ b/OnTopic/Mapping/Internal/ItemConfiguration.cs @@ -250,9 +250,9 @@ internal ItemConfiguration(ItemMetadata itemMetadata) { /// /// /// By default, a collection property on a model class will be mapped to a corresponding collection of the same name. - /// So, for instance, if the property on the model class is called Cousins then the will search , , , and, finally, for an object named Cousins. If + /// So, for instance, if the property on the model class is called Cousins then the will search , , , and, finally, for an object named Cousins. If /// the is set, however, then that value is used instead, thus allowing the property on the /// model to be aliased to a different collection name on the source . /// @@ -274,8 +274,8 @@ internal ItemConfiguration(ItemMetadata itemMetadata) { /// By default, a collection property on a model class will attempt to find a match from, in order, , , , and, finally, . If the is set, however, then the will only map the collection to a collection of that type. This can be valuable when the might be ambiguous between multiple collections. + /// /> will only map the collection to a collection of that type. This can be valuable when the might be ambiguous between multiple collections. /// /// /// The property corresponds to the property. It diff --git a/OnTopic/Mapping/Internal/MappedTopicCacheEntry.cs b/OnTopic/Mapping/Internal/MappedTopicCacheEntry.cs index 51f8eeb8..e37fb3b6 100644 --- a/OnTopic/Mapping/Internal/MappedTopicCacheEntry.cs +++ b/OnTopic/Mapping/Internal/MappedTopicCacheEntry.cs @@ -16,8 +16,8 @@ namespace OnTopic.Mapping.Internal; /// /// In addition to the actual , this also includes a property for /// tracking what associations were mapped to the . This allows the to be update the cached object with any missing associations, which can be identified using the method. In turn, the cache can then be updated to reflect those new +/// /> to be update the cached object with any missing associations, which can be identified using the method. In turn, the cache can then be updated to reflect those new /// associations by using . This ensures that even if a topic has /// already been mapped, its scope can be expanded without duplicating effort. /// @@ -67,8 +67,8 @@ internal sealed class MappedTopicCacheEntry { | METHOD: ADD MISSING ASSOCIATIONS \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Given a target , adds any missing to the property. + /// Given a target , adds any missing to the property. /// internal void AddMissingAssociations(AssociationTypes associations) => Associations = associations | Associations; diff --git a/OnTopic/Mapping/TopicMappingService.cs b/OnTopic/Mapping/TopicMappingService.cs index aa9455e1..6a05501a 100644 --- a/OnTopic/Mapping/TopicMappingService.cs +++ b/OnTopic/Mapping/TopicMappingService.cs @@ -617,8 +617,8 @@ await MapAsync( /// /// The method will attempt to retrieve the value from the /// based on, in order, the 's Get{Property}() method, - /// {Property} property, and, finally, its collection (using ). + /// {Property} property, and, finally, its collection (using ). /// /// The source from which to pull the value. /// The with details about the property's attributes. diff --git a/OnTopic/Models/IAssociatedTopicBindingModel.cs b/OnTopic/Models/IAssociatedTopicBindingModel.cs index 4e2a89a2..1182511e 100644 --- a/OnTopic/Models/IAssociatedTopicBindingModel.cs +++ b/OnTopic/Models/IAssociatedTopicBindingModel.cs @@ -15,8 +15,8 @@ namespace OnTopic.Models; /// Provides a generic data transfer topic for binding an association of a binding model to an existing . /// /// -/// It is strictly required that any binding models used as associations implement the interface for the default to correctly identify +/// It is strictly required that any binding models used as associations implement the interface for the default to correctly identify /// and map an association back to a . /// public interface IAssociatedTopicBindingModel { diff --git a/OnTopic/Models/ITopicViewModel.cs b/OnTopic/Models/ITopicViewModel.cs index 2c77ec7d..ef6e6ea7 100644 --- a/OnTopic/Models/ITopicViewModel.cs +++ b/OnTopic/Models/ITopicViewModel.cs @@ -23,8 +23,8 @@ namespace OnTopic.Models; /// /// /// For instance, in the default MVC library, the TopicViewResult class requires that the and be supplied separately if they're not provided as part of a . The exact details of this will obviously vary based on the implementation of the presentation +/// ContentType"/> and be supplied separately if they're not provided as part of a . The exact details of this will obviously vary based on the implementation of the presentation /// layer and any supporting libraries. /// /// @@ -56,8 +56,8 @@ public interface ITopicViewModel: ICoreTopicViewModel, IAssociatedTopicBindingMo /// /// /// This value can be set via the query string (via the TopicViewResultExecutor class), via the Accepts header - /// (also via the TopicViewResultExecutor class), on the topic itself (via this property), or via the . By default, it will be set to the name of the . By default, it will be set to the name of the ; e.g., if the Content Type is Page, then the view will be Page. This will cause the /// TopicViewResultExecutor to look for a view at, for instance, /Views/Page/Page.cshtml. /// diff --git a/OnTopic/Obsolete/Attributes/AttributeValue.cs b/OnTopic/Obsolete/Attributes/AttributeValue.cs index acd753f0..43e352ce 100644 --- a/OnTopic/Obsolete/Attributes/AttributeValue.cs +++ b/OnTopic/Obsolete/Attributes/AttributeValue.cs @@ -203,8 +203,8 @@ internal AttributeValue( /// cref="IsDirty"/> to determine if a value should be saved. If an attribute's value hasn't changed, but the location /// it should be stored has, that could potentially result in the attribute being deleted, as the attribute won't show /// up for when is called with isDirty set to true and - /// isExtendedAttribute is set to either true or false. By introducing , the is able to detect conflicts between the configuration and + /// isExtendedAttribute is set to either true or false. By introducing , the is able to detect conflicts between the configuration and /// the underlying data store, and ensure data is stored appropriately. /// /// diff --git a/OnTopic/Querying/TopicCollectionExtensions.cs b/OnTopic/Querying/TopicCollectionExtensions.cs index 8bcb01ab..8ce85a36 100644 --- a/OnTopic/Querying/TopicCollectionExtensions.cs +++ b/OnTopic/Querying/TopicCollectionExtensions.cs @@ -25,8 +25,8 @@ public static class TopicCollectionExtensions { /// /// /// This does not determine if the collection itself is dirty—it only determines if any instances in - /// the collection are . This distinction is important. For example, if a clean is added to the collection, then the collection will be dirty—but + /// the collection are . This distinction is important. For example, if a clean is added to the collection, then the collection will be dirty—but /// will be false. /// /// The collection of instances to operate against. diff --git a/OnTopic/Repositories/ITopicRepository.cs b/OnTopic/Repositories/ITopicRepository.cs index 17b9965f..8b4aa259 100644 --- a/OnTopic/Repositories/ITopicRepository.cs +++ b/OnTopic/Repositories/ITopicRepository.cs @@ -32,20 +32,20 @@ public interface ITopicRepository { event EventHandler TopicLoaded; /// - /// Raised after a is saved in the as part of a operation. + /// Raised after a is saved in the as part of a operation. /// event EventHandler TopicSaved; /// - /// Raised after a is deleted from the as part of a operation. + /// Raised after a is deleted from the as part of a operation. /// event EventHandler TopicDeleted; /// - /// Raised after a is moved within the as part of a operation. + /// Raised after a is moved within the as part of a operation. /// event EventHandler TopicMoved; diff --git a/OnTopic/Repositories/TopicRepository.cs b/OnTopic/Repositories/TopicRepository.cs index b7952a1c..509736d2 100644 --- a/OnTopic/Repositories/TopicRepository.cs +++ b/OnTopic/Repositories/TopicRepository.cs @@ -28,8 +28,8 @@ namespace OnTopic.Repositories; /// /// /// Implementations of which need to use different business logic, or do not need to -/// implement business logic (such as unit test doubles) may instead opt to derive directly from the , which handles the basic event handling, and nothing else. Implementations of decorators +/// implement business logic (such as unit test doubles) may instead opt to derive directly from the , which handles the basic event handling, and nothing else. Implementations of decorators /// should instead derive from the . /// /// @@ -469,10 +469,10 @@ _contentTypeDescriptors is not null && /// /// /// The main implementation handles advanced validation of the parameters, updating the - /// , attempting to pick up any unresolved topics, updating and instances as appropriate, raising the , if needed, and recursing over children. The derived implementation of is then left to focus exclusively on the core logic of persisting the changes + /// , attempting to pick up any unresolved topics, updating and instances as appropriate, raising the , if needed, and recursing over children. The derived implementation of is then left to focus exclusively on the core logic of persisting the changes /// to the individual to the underlying data store, and optionally updating its and , assuming is set to /// true. @@ -695,8 +695,8 @@ public override sealed async Task Delete([ValidatedNotNull]Topic topic, bool isR /// /// /// The main implementation handles advanced validation of the parameters, - /// removing the from the topic graph, updating and instances as appropriate, and raising the . The + /// removing the from the topic graph, updating and instances as appropriate, and raising the . The /// derived implementation of is then left to focus exclusively on the core logic of /// persisting the change to the underlying data store. /// @@ -799,8 +799,8 @@ protected IEnumerable GetAttributes( | METHOD: GET UNMATCHED ATTRIBUTES \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Given a , identifies s that are defined based on the , but aren't defined in the . + /// Given a , identifies s that are defined based on the , but aren't defined in the . /// /// The from which to pull the attributes. protected IEnumerable GetUnmatchedAttributes(Topic topic) { diff --git a/OnTopic/Repositories/_eventArgs/TopicSaveEventArgs.cs b/OnTopic/Repositories/_eventArgs/TopicSaveEventArgs.cs index 73f251aa..71413483 100644 --- a/OnTopic/Repositories/_eventArgs/TopicSaveEventArgs.cs +++ b/OnTopic/Repositories/_eventArgs/TopicSaveEventArgs.cs @@ -37,8 +37,8 @@ public TopicSaveEventArgs(Topic topic, bool isRecursive, bool isNew): base(topic | PROPERTY: IS NEW \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Gets or sets whether the was newly created, or if it was an existing that has been updated. + /// Gets or sets whether the was newly created, or if it was an existing that has been updated. /// public bool IsNew { get; set; } diff --git a/OnTopic/Topic.cs b/OnTopic/Topic.cs index cce13b1f..854f51c8 100644 --- a/OnTopic/Topic.cs +++ b/OnTopic/Topic.cs @@ -43,8 +43,8 @@ public class Topic: ITrackDirtyKeys, ITopicBackingAccessor { /// optionally, , . /// /// - /// By default, when creating new attributes, the s for both and will be set to , which is required in order to correctly save new + /// By default, when creating new attributes, the s for both and will be set to , which is required in order to correctly save new /// topics to the database. When the parameter is set, however, the property is set to falseon and , as it is assumed these /// are being set to the same values currently used in the persistence store. @@ -850,16 +850,16 @@ public void MarkClean(string key, bool includeCollections) { /// local value for the attribute. /// /// - /// Be aware that while multiple levels of s can be configured, the method defaults to a maximum level + /// Be aware that while multiple levels of s can be configured, the method defaults to a maximum level /// of five "hops" in order to help avoid an infinite loop. /// /// /// The underlying value of the is stored as a topic reference with the of BaseTopic in . If the hasn't been /// saved, then the reference will be established, but the BaseTopic won't be persisted to the underlying - /// repository upon . That said, when is called, the will be reevaluated + /// repository upon . That said, when is called, the will be reevaluated /// and, if it has subsequently been saved, and the BaseTopic will be updated accordingly. This allows in-memory /// topic graphs to be constructed, while preventing invalid s from being persisted to the /// underlying data storage. As a result, however, a referencing an that is @@ -995,8 +995,8 @@ public TopicReferenceCollection References { /// /// When an attribute value is set and a corresponding, writable property exists on the topic, that property will be /// called by the . This is intended to enforce local business logic, and prevent callers - /// from introducing invalid data.To prevent a redirect loop, however, local properties need to inform the that the business logic has already been enforced. To do that, they must either call that the business logic has already been enforced. To do that, they must either call with the /// enforceBusinessLogic flag set to false, or, if they're in a separate assembly, call this overload. /// From b280e4317a51a9c1cc954fa0f35be8554f749c15 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Thu, 9 Jul 2026 00:06:35 -0700 Subject: [PATCH 120/337] Reintroduced types for constructors This partially undoes work committed previously (5c6bd856) in preferring implicit constructors where the type is known. There were some false positives! --- OnTopic.Data.Sql/Models/AttributeValuesDataTable.cs | 4 ++-- OnTopic.Data.Sql/Models/TopicListDataTable.cs | 2 +- OnTopic.Data.Sql/Models/TopicReferencesDataTable.cs | 4 ++-- OnTopic.Tests/Schemas/AttributesDataTable.cs | 8 ++++---- OnTopic.Tests/Schemas/ExtendedAttributesDataTable.cs | 6 +++--- OnTopic.Tests/Schemas/RelationshipsDataTable.cs | 10 +++++----- OnTopic.Tests/Schemas/TopicReferencesDataTable.cs | 8 ++++---- OnTopic.Tests/Schemas/TopicsDataTable.cs | 12 ++++++------ OnTopic.Tests/Schemas/VersionHistoryDataTable.cs | 4 ++-- OnTopic.Tests/TopicRepositoryBaseTest.cs | 2 +- 10 files changed, 30 insertions(+), 30 deletions(-) diff --git a/OnTopic.Data.Sql/Models/AttributeValuesDataTable.cs b/OnTopic.Data.Sql/Models/AttributeValuesDataTable.cs index 35ec53fa..fd3d86cb 100644 --- a/OnTopic.Data.Sql/Models/AttributeValuesDataTable.cs +++ b/OnTopic.Data.Sql/Models/AttributeValuesDataTable.cs @@ -29,7 +29,7 @@ internal AttributeValuesDataTable() { | COLUMN: Attribute Key \-------------------------------------------------------------------------------------------------------------------------*/ Columns.Add( - new("AttributeKey") { + new DataColumn("AttributeKey") { MaxLength = 128 } ); @@ -38,7 +38,7 @@ internal AttributeValuesDataTable() { | COLUMN: Attribute Value \-------------------------------------------------------------------------------------------------------------------------*/ Columns.Add( - new("AttributeRecord") { + new DataColumn("AttributeRecord") { MaxLength = 255 } ); diff --git a/OnTopic.Data.Sql/Models/TopicListDataTable.cs b/OnTopic.Data.Sql/Models/TopicListDataTable.cs index c41b05d1..38715b44 100644 --- a/OnTopic.Data.Sql/Models/TopicListDataTable.cs +++ b/OnTopic.Data.Sql/Models/TopicListDataTable.cs @@ -27,7 +27,7 @@ internal TopicListDataTable() { | COLUMN: Topic ID \-------------------------------------------------------------------------------------------------------------------------*/ Columns.Add( - new("TopicID", typeof(int)) + new DataColumn("TopicID", typeof(int)) ); } diff --git a/OnTopic.Data.Sql/Models/TopicReferencesDataTable.cs b/OnTopic.Data.Sql/Models/TopicReferencesDataTable.cs index e1e934f2..b3d98c15 100644 --- a/OnTopic.Data.Sql/Models/TopicReferencesDataTable.cs +++ b/OnTopic.Data.Sql/Models/TopicReferencesDataTable.cs @@ -27,7 +27,7 @@ internal TopicReferencesDataTable() { | COLUMN: Reference Key \-------------------------------------------------------------------------------------------------------------------------*/ Columns.Add( - new("ReferenceKey") { + new DataColumn("ReferenceKey") { MaxLength = 128 } ); @@ -36,7 +36,7 @@ internal TopicReferencesDataTable() { | COLUMN: Topic ID \-------------------------------------------------------------------------------------------------------------------------*/ Columns.Add( - new("TopicID", typeof(int)) + new DataColumn("TopicID", typeof(int)) ); } diff --git a/OnTopic.Tests/Schemas/AttributesDataTable.cs b/OnTopic.Tests/Schemas/AttributesDataTable.cs index 0da03b99..0dc8dae0 100644 --- a/OnTopic.Tests/Schemas/AttributesDataTable.cs +++ b/OnTopic.Tests/Schemas/AttributesDataTable.cs @@ -32,7 +32,7 @@ public AttributesDataTable() : base("Attributes") { /*-------------------------------------------------------------------------------------------------------------------------- | Add TopicId column \-------------------------------------------------------------------------------------------------------------------------*/ - Columns.Add(new() { + Columns.Add(new DataColumn() { DataType = typeof(int), ColumnName = "TopicId", Unique = true @@ -41,7 +41,7 @@ public AttributesDataTable() : base("Attributes") { /*-------------------------------------------------------------------------------------------------------------------------- | Add AttributeKey column \-------------------------------------------------------------------------------------------------------------------------*/ - Columns.Add(new() { + Columns.Add(new DataColumn() { DataType = typeof(string), ColumnName = "AttributeKey" }); @@ -49,7 +49,7 @@ public AttributesDataTable() : base("Attributes") { /*-------------------------------------------------------------------------------------------------------------------------- | Add AttributeValue column \-------------------------------------------------------------------------------------------------------------------------*/ - Columns.Add(new() { + Columns.Add(new DataColumn() { DataType = typeof(string), ColumnName = "AttributeValue", AllowDBNull = true @@ -58,7 +58,7 @@ public AttributesDataTable() : base("Attributes") { /*-------------------------------------------------------------------------------------------------------------------------- | Add Version column \-------------------------------------------------------------------------------------------------------------------------*/ - Columns.Add(new() { + Columns.Add(new DataColumn() { DataType = typeof(DateTime), ColumnName = "Version" }); diff --git a/OnTopic.Tests/Schemas/ExtendedAttributesDataTable.cs b/OnTopic.Tests/Schemas/ExtendedAttributesDataTable.cs index f30ba40a..353a6b85 100644 --- a/OnTopic.Tests/Schemas/ExtendedAttributesDataTable.cs +++ b/OnTopic.Tests/Schemas/ExtendedAttributesDataTable.cs @@ -33,7 +33,7 @@ public ExtendedAttributesDataTable() : base("ExtendedAttributes") { /*-------------------------------------------------------------------------------------------------------------------------- | Add TopicId column \-------------------------------------------------------------------------------------------------------------------------*/ - Columns.Add(new() { + Columns.Add(new DataColumn() { DataType = typeof(int), ColumnName = "TopicId", Unique = true @@ -42,7 +42,7 @@ public ExtendedAttributesDataTable() : base("ExtendedAttributes") { /*-------------------------------------------------------------------------------------------------------------------------- | Add AttributesXml column \-------------------------------------------------------------------------------------------------------------------------*/ - Columns.Add(new() { + Columns.Add(new DataColumn() { DataType = typeof(XmlDocument), ColumnName = "AttributesXml" }); @@ -50,7 +50,7 @@ public ExtendedAttributesDataTable() : base("ExtendedAttributes") { /*-------------------------------------------------------------------------------------------------------------------------- | Add Version column \-------------------------------------------------------------------------------------------------------------------------*/ - Columns.Add(new() { + Columns.Add(new DataColumn() { DataType = typeof(DateTime), ColumnName = "Version" }); diff --git a/OnTopic.Tests/Schemas/RelationshipsDataTable.cs b/OnTopic.Tests/Schemas/RelationshipsDataTable.cs index 3bd93cc4..c465c65e 100644 --- a/OnTopic.Tests/Schemas/RelationshipsDataTable.cs +++ b/OnTopic.Tests/Schemas/RelationshipsDataTable.cs @@ -32,7 +32,7 @@ public RelationshipsDataTable() : base("Relationships") { /*-------------------------------------------------------------------------------------------------------------------------- | Add Source_TopicId column \-------------------------------------------------------------------------------------------------------------------------*/ - Columns.Add(new() { + Columns.Add(new DataColumn() { DataType = typeof(int), ColumnName = "Source_TopicId", Unique = true @@ -41,7 +41,7 @@ public RelationshipsDataTable() : base("Relationships") { /*-------------------------------------------------------------------------------------------------------------------------- | Add RelationshipKey column \-------------------------------------------------------------------------------------------------------------------------*/ - Columns.Add(new() { + Columns.Add(new DataColumn() { DataType = typeof(string), ColumnName = "RelationshipKey" }); @@ -49,7 +49,7 @@ public RelationshipsDataTable() : base("Relationships") { /*-------------------------------------------------------------------------------------------------------------------------- | Add Target_TopicId column \-------------------------------------------------------------------------------------------------------------------------*/ - Columns.Add(new() { + Columns.Add(new DataColumn() { DataType = typeof(int), ColumnName = "Target_TopicId" }); @@ -57,7 +57,7 @@ public RelationshipsDataTable() : base("Relationships") { /*-------------------------------------------------------------------------------------------------------------------------- | Add IsDeleted column \-------------------------------------------------------------------------------------------------------------------------*/ - Columns.Add(new() { + Columns.Add(new DataColumn() { DataType = typeof(bool), ColumnName = "IsDeleted" }); @@ -65,7 +65,7 @@ public RelationshipsDataTable() : base("Relationships") { /*-------------------------------------------------------------------------------------------------------------------------- | Add ParentId column \-------------------------------------------------------------------------------------------------------------------------*/ - Columns.Add(new() { + Columns.Add(new DataColumn() { DataType = typeof(DateTime), ColumnName = "Version" }); diff --git a/OnTopic.Tests/Schemas/TopicReferencesDataTable.cs b/OnTopic.Tests/Schemas/TopicReferencesDataTable.cs index c722b8db..ccc42ced 100644 --- a/OnTopic.Tests/Schemas/TopicReferencesDataTable.cs +++ b/OnTopic.Tests/Schemas/TopicReferencesDataTable.cs @@ -32,7 +32,7 @@ public TopicReferencesDataTable() : base("TopicReferences") { /*-------------------------------------------------------------------------------------------------------------------------- | Add Source_TopicId column \-------------------------------------------------------------------------------------------------------------------------*/ - Columns.Add(new() { + Columns.Add(new DataColumn() { DataType = typeof(int), ColumnName = "Source_TopicId", Unique = true @@ -41,7 +41,7 @@ public TopicReferencesDataTable() : base("TopicReferences") { /*-------------------------------------------------------------------------------------------------------------------------- | Add RelationshipKey column \-------------------------------------------------------------------------------------------------------------------------*/ - Columns.Add(new() { + Columns.Add(new DataColumn() { DataType = typeof(string), ColumnName = "ReferenceKey" }); @@ -49,7 +49,7 @@ public TopicReferencesDataTable() : base("TopicReferences") { /*-------------------------------------------------------------------------------------------------------------------------- | Add Target_TopicId column \-------------------------------------------------------------------------------------------------------------------------*/ - Columns.Add(new() { + Columns.Add(new DataColumn() { DataType = typeof(int), ColumnName = "Target_TopicId", AllowDBNull = true @@ -58,7 +58,7 @@ public TopicReferencesDataTable() : base("TopicReferences") { /*-------------------------------------------------------------------------------------------------------------------------- | Add ParentId column \-------------------------------------------------------------------------------------------------------------------------*/ - Columns.Add(new() { + Columns.Add(new DataColumn() { DataType = typeof(DateTime), ColumnName = "Version" }); diff --git a/OnTopic.Tests/Schemas/TopicsDataTable.cs b/OnTopic.Tests/Schemas/TopicsDataTable.cs index 9102674b..b13fd38c 100644 --- a/OnTopic.Tests/Schemas/TopicsDataTable.cs +++ b/OnTopic.Tests/Schemas/TopicsDataTable.cs @@ -32,7 +32,7 @@ public TopicsDataTable() : base("Topics") { /*-------------------------------------------------------------------------------------------------------------------------- | Add TopicId column \-------------------------------------------------------------------------------------------------------------------------*/ - Columns.Add(new() { + Columns.Add(new DataColumn() { DataType = typeof(int), ColumnName = "TopicId", Unique = true @@ -41,7 +41,7 @@ public TopicsDataTable() : base("Topics") { /*-------------------------------------------------------------------------------------------------------------------------- | Add TopicKey column \-------------------------------------------------------------------------------------------------------------------------*/ - Columns.Add(new() { + Columns.Add(new DataColumn() { DataType = typeof(string), ColumnName = "TopicKey" }); @@ -49,7 +49,7 @@ public TopicsDataTable() : base("Topics") { /*-------------------------------------------------------------------------------------------------------------------------- | Add ContentType column \-------------------------------------------------------------------------------------------------------------------------*/ - Columns.Add(new() { + Columns.Add(new DataColumn() { DataType = typeof(string), ColumnName = "ContentType" }); @@ -57,7 +57,7 @@ public TopicsDataTable() : base("Topics") { /*-------------------------------------------------------------------------------------------------------------------------- | Add ParentId column \-------------------------------------------------------------------------------------------------------------------------*/ - Columns.Add(new() { + Columns.Add(new DataColumn() { DataType = typeof(int), ColumnName = "ParentId", AllowDBNull = true @@ -66,7 +66,7 @@ public TopicsDataTable() : base("Topics") { /*-------------------------------------------------------------------------------------------------------------------------- | Add HasChildren column \-------------------------------------------------------------------------------------------------------------------------*/ - Columns.Add(new() { + Columns.Add(new DataColumn() { DataType = typeof(bool), ColumnName = "HasChildren", AllowDBNull = true @@ -75,7 +75,7 @@ public TopicsDataTable() : base("Topics") { /*-------------------------------------------------------------------------------------------------------------------------- | Add HasExtendedAttributes column \-------------------------------------------------------------------------------------------------------------------------*/ - Columns.Add(new() { + Columns.Add(new DataColumn() { DataType = typeof(bool), ColumnName = "HasExtendedAttributes", AllowDBNull = true diff --git a/OnTopic.Tests/Schemas/VersionHistoryDataTable.cs b/OnTopic.Tests/Schemas/VersionHistoryDataTable.cs index 14a3666f..fce2a573 100644 --- a/OnTopic.Tests/Schemas/VersionHistoryDataTable.cs +++ b/OnTopic.Tests/Schemas/VersionHistoryDataTable.cs @@ -33,7 +33,7 @@ public VersionHistoryDataTable() : base("VersionHistory") { /*-------------------------------------------------------------------------------------------------------------------------- | Add TopicId column \-------------------------------------------------------------------------------------------------------------------------*/ - Columns.Add(new() { + Columns.Add(new DataColumn() { DataType = typeof(int), ColumnName = "TopicId", Unique = true @@ -42,7 +42,7 @@ public VersionHistoryDataTable() : base("VersionHistory") { /*-------------------------------------------------------------------------------------------------------------------------- | Add Version column \-------------------------------------------------------------------------------------------------------------------------*/ - Columns.Add(new() { + Columns.Add(new DataColumn() { DataType = typeof(DateTime), ColumnName = "Version" }); diff --git a/OnTopic.Tests/TopicRepositoryBaseTest.cs b/OnTopic.Tests/TopicRepositoryBaseTest.cs index cfd19e27..7dd8d608 100644 --- a/OnTopic.Tests/TopicRepositoryBaseTest.cs +++ b/OnTopic.Tests/TopicRepositoryBaseTest.cs @@ -185,7 +185,7 @@ await Assert.ThrowsAsync(() => [Fact] public async Task Load_OldDate_ThrowsException() => await Assert.ThrowsAsync(() => - _cachedTopicRepository.Load(1111, new(2010, 10, 15)) + _cachedTopicRepository.Load(1111, new DateTime(2010, 10, 15)) ); /*============================================================================================================================ From e05427ff1444fe11083408995dde0113f1f42a13 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Thu, 9 Jul 2026 00:12:25 -0700 Subject: [PATCH 121/337] Prefer implicit constructors if type known (cont.) This continues previous implementations (56379ac2, 5c6bd856), picking up some missing references. --- OnTopic.Tests/KeyedTopicCollectionTest.cs | 4 ++-- OnTopic.Tests/TopicQueryingTest.cs | 8 ++++---- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/OnTopic.Tests/KeyedTopicCollectionTest.cs b/OnTopic.Tests/KeyedTopicCollectionTest.cs index c0702b77..5dc8c5ec 100644 --- a/OnTopic.Tests/KeyedTopicCollectionTest.cs +++ b/OnTopic.Tests/KeyedTopicCollectionTest.cs @@ -68,8 +68,8 @@ public void Constructor_IEnumerable_SeedsTopics() { public void InsertItem_DuplicateKey_ThrowsException() => Assert.Throws(() => new KeyedTopicCollection { - new Topic("Key", "Page"), - new Topic("Key", "Page") + new("Key", "Page"), + new("Key", "Page") } ); diff --git a/OnTopic.Tests/TopicQueryingTest.cs b/OnTopic.Tests/TopicQueryingTest.cs index 73ecbccf..f822404e 100644 --- a/OnTopic.Tests/TopicQueryingTest.cs +++ b/OnTopic.Tests/TopicQueryingTest.cs @@ -290,7 +290,7 @@ public async Task GetContentType_InvalidType_ReturnsNull() { public void AnyDirty_DirtyCollection_ReturnTrue() { var topics = new TopicCollection { - new Topic("Test", "Page") + new("Test", "Page") }; Assert.True(topics.AnyDirty()); @@ -308,7 +308,7 @@ public void AnyDirty_DirtyCollection_ReturnTrue() { public void AnyDirty_CleanCollection_ReturnFalse() { var topics = new TopicCollection { - new Topic("Test", "Page", null, 1) + new("Test", "Page", null, 1) }; Assert.False(topics.AnyDirty()); @@ -326,7 +326,7 @@ public void AnyDirty_CleanCollection_ReturnFalse() { public void AnyNew_ContainsNew_ReturnTrue() { var topics = new TopicCollection { - new Topic("Test", "Page") + new("Test", "Page") }; Assert.True(topics.AnyNew()); @@ -344,7 +344,7 @@ public void AnyNew_ContainsNew_ReturnTrue() { public void AnyNew_ContainsExisting_ReturnFalse() { var topics = new TopicCollection { - new Topic("Test", "Page", null, 1) + new("Test", "Page", null, 1) }; Assert.False(topics.AnyNew()); From 0afc9841634fd34f5e08e8c876e75cc59192762d Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Thu, 9 Jul 2026 00:18:42 -0700 Subject: [PATCH 122/337] Accept implicit base/default constructor If defining a constructor, the base default constructor will always be called. This isn't intuitive to me, but you learn something new every day. (Also, a word of caution when implementing base default constructors!). --- .../Repositories/StubTopicRepository.cs | 2 +- OnTopic.AspNetCore.Mvc.Tests/TestDoubles/TestTopicRepository.cs | 2 +- OnTopic.AspNetCore.Mvc/TopicViewResult.cs | 2 +- OnTopic.Data.Sql/SqlTopicRepository.cs | 2 +- OnTopic.TestDoubles/DummyTopicRepository.cs | 2 +- OnTopic.TestDoubles/StubTopicRepository.cs | 2 +- OnTopic.Tests/TestDoubles/FakeViewModelLookupService.cs | 2 +- OnTopic/Collections/Specialized/DirtyKeyCollection.cs | 2 +- OnTopic/Collections/Specialized/TopicIndex.cs | 2 +- OnTopic/Lookup/DynamicTypeLookupService.cs | 2 +- OnTopic/Mapping/_exceptions/InvalidTypeException.cs | 2 +- OnTopic/Mapping/_exceptions/MappingModelValidationException.cs | 2 +- OnTopic/Mapping/_exceptions/TopicMappingException.cs | 2 +- OnTopic/Obsolete/Collections/NamedTopicCollection.cs | 2 +- OnTopic/Obsolete/Repositories/DeleteEventArgs.cs | 2 +- OnTopic/Repositories/TopicRepositoryDecorator.cs | 2 +- OnTopic/Repositories/_eventArgs/TopicEventArgs.cs | 2 +- .../Repositories/_exceptions/ReferentialIntegrityException.cs | 2 +- OnTopic/Repositories/_exceptions/TopicNotFoundException.cs | 2 +- OnTopic/Repositories/_exceptions/TopicRepositoryException.cs | 2 +- 20 files changed, 20 insertions(+), 20 deletions(-) diff --git a/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/Repositories/StubTopicRepository.cs b/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/Repositories/StubTopicRepository.cs index 700667e1..31cc6efd 100644 --- a/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/Repositories/StubTopicRepository.cs +++ b/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/Repositories/StubTopicRepository.cs @@ -33,7 +33,7 @@ public class StubTopicRepository : TopicRepository, ITopicRepository { /// Instantiates a new instance of the StubTopicRepository. /// /// A new instance of the StubTopicRepository. - public StubTopicRepository() : base() { + public StubTopicRepository() { _cache = CreateFakeData(); Contract.Assume(_cache); } diff --git a/OnTopic.AspNetCore.Mvc.Tests/TestDoubles/TestTopicRepository.cs b/OnTopic.AspNetCore.Mvc.Tests/TestDoubles/TestTopicRepository.cs index 18385ec0..034e553d 100644 --- a/OnTopic.AspNetCore.Mvc.Tests/TestDoubles/TestTopicRepository.cs +++ b/OnTopic.AspNetCore.Mvc.Tests/TestDoubles/TestTopicRepository.cs @@ -34,7 +34,7 @@ public class TestTopicRepository: DummyTopicRepository { /// Instantiates a new instance of the StubTopicRepository. /// /// A new instance of the StubTopicRepository. - public TestTopicRepository() : base() { + public TestTopicRepository() { _cache = CreateFakeData(); Contract.Assume(_cache); } diff --git a/OnTopic.AspNetCore.Mvc/TopicViewResult.cs b/OnTopic.AspNetCore.Mvc/TopicViewResult.cs index cd2125da..2908fc06 100644 --- a/OnTopic.AspNetCore.Mvc/TopicViewResult.cs +++ b/OnTopic.AspNetCore.Mvc/TopicViewResult.cs @@ -35,7 +35,7 @@ public TopicViewResult( object viewModel, string? contentType = null, string? view = null - ) : base() { + ) { /*-------------------------------------------------------------------------------------------------------------------------- | Validate parameters diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index 1fb88a72..f82a6163 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -37,7 +37,7 @@ public class SqlTopicRepository : TopicRepository, ITopicRepository, ITopicLoadR /// /// A connection string to a SQL server that contains the Topics database. /// A new instance of the SqlTopicRepository. - public SqlTopicRepository(string connectionString) : base() { + public SqlTopicRepository(string connectionString) { /*-------------------------------------------------------------------------------------------------------------------------- | Validate parameters diff --git a/OnTopic.TestDoubles/DummyTopicRepository.cs b/OnTopic.TestDoubles/DummyTopicRepository.cs index 4d382b20..903c2faa 100644 --- a/OnTopic.TestDoubles/DummyTopicRepository.cs +++ b/OnTopic.TestDoubles/DummyTopicRepository.cs @@ -24,7 +24,7 @@ public class DummyTopicRepository : ObservableTopicRepository { /// Instantiates a new instance of the . /// /// A new instance of the . - public DummyTopicRepository() : base() { } + public DummyTopicRepository() { } /*============================================================================================================================ | METHOD: GET CONTENT TYPE DESCRIPTORS diff --git a/OnTopic.TestDoubles/StubTopicRepository.cs b/OnTopic.TestDoubles/StubTopicRepository.cs index 5553e51e..d42c6527 100644 --- a/OnTopic.TestDoubles/StubTopicRepository.cs +++ b/OnTopic.TestDoubles/StubTopicRepository.cs @@ -38,7 +38,7 @@ public class StubTopicRepository : TopicRepository, ITopicRepository, ITopicLoad /// Instantiates a new instance of the StubTopicRepository. /// /// A new instance of the StubTopicRepository. - public StubTopicRepository() : base() { + public StubTopicRepository() { _cache = CreateFakeData(); Contract.Assume(_cache); } diff --git a/OnTopic.Tests/TestDoubles/FakeViewModelLookupService.cs b/OnTopic.Tests/TestDoubles/FakeViewModelLookupService.cs index eee92154..fc379c2d 100644 --- a/OnTopic.Tests/TestDoubles/FakeViewModelLookupService.cs +++ b/OnTopic.Tests/TestDoubles/FakeViewModelLookupService.cs @@ -27,7 +27,7 @@ public class FakeViewModelLookupService: TopicViewModelLookupService { /// Instantiates a new instance of the . /// /// A new instance of the . - public FakeViewModelLookupService() : base() { + public FakeViewModelLookupService() { /*-------------------------------------------------------------------------------------------------------------------------- | Add test specific view models diff --git a/OnTopic/Collections/Specialized/DirtyKeyCollection.cs b/OnTopic/Collections/Specialized/DirtyKeyCollection.cs index 54cb27db..ac85fe58 100644 --- a/OnTopic/Collections/Specialized/DirtyKeyCollection.cs +++ b/OnTopic/Collections/Specialized/DirtyKeyCollection.cs @@ -25,7 +25,7 @@ internal sealed class DirtyKeyCollection : Collection, ITrackDirtyKeys { /// /// Initializes a new instance of the . /// - public DirtyKeyCollection() : base() {} + public DirtyKeyCollection() {} /*============================================================================================================================ | METHOD: IS DIRTY? diff --git a/OnTopic/Collections/Specialized/TopicIndex.cs b/OnTopic/Collections/Specialized/TopicIndex.cs index 85cb6ee7..0b0a49c8 100644 --- a/OnTopic/Collections/Specialized/TopicIndex.cs +++ b/OnTopic/Collections/Specialized/TopicIndex.cs @@ -21,7 +21,7 @@ public class TopicIndex : Dictionary { /// Initializes a new instance of the . /// /// Seeds the collection with an optional list of topic references. - public TopicIndex(IEnumerable? topics = null) : base() { + public TopicIndex(IEnumerable? topics = null) { if (topics is not null) { foreach(var topic in topics) { Add(topic.Id, topic); diff --git a/OnTopic/Lookup/DynamicTypeLookupService.cs b/OnTopic/Lookup/DynamicTypeLookupService.cs index dbf938e0..ad3b230d 100644 --- a/OnTopic/Lookup/DynamicTypeLookupService.cs +++ b/OnTopic/Lookup/DynamicTypeLookupService.cs @@ -23,7 +23,7 @@ public class DynamicTypeLookupService : StaticTypeLookupService { /// optionally, a default object to return if none is specified. /// /// The search condition to use to identify target classes. - public DynamicTypeLookupService(Func predicate) : base() { + public DynamicTypeLookupService(Func predicate) { /*-------------------------------------------------------------------------------------------------------------------------- | Find target classes diff --git a/OnTopic/Mapping/_exceptions/InvalidTypeException.cs b/OnTopic/Mapping/_exceptions/InvalidTypeException.cs index 3bfaf613..a63f18cf 100644 --- a/OnTopic/Mapping/_exceptions/InvalidTypeException.cs +++ b/OnTopic/Mapping/_exceptions/InvalidTypeException.cs @@ -28,7 +28,7 @@ public class InvalidTypeException: TopicMappingException { /// /// Initializes a new instance. /// - public InvalidTypeException() : base() { } + public InvalidTypeException() { } /// /// Initializes a new instance with a specific error message. diff --git a/OnTopic/Mapping/_exceptions/MappingModelValidationException.cs b/OnTopic/Mapping/_exceptions/MappingModelValidationException.cs index aff6c2ce..bdc587f8 100644 --- a/OnTopic/Mapping/_exceptions/MappingModelValidationException.cs +++ b/OnTopic/Mapping/_exceptions/MappingModelValidationException.cs @@ -32,7 +32,7 @@ public class MappingModelValidationException: TopicMappingException { /// /// Initializes a new instance. /// - public MappingModelValidationException() : base() { } + public MappingModelValidationException() { } /// /// Initializes a new instance with a specific error message. diff --git a/OnTopic/Mapping/_exceptions/TopicMappingException.cs b/OnTopic/Mapping/_exceptions/TopicMappingException.cs index 450d16fd..230c3d76 100644 --- a/OnTopic/Mapping/_exceptions/TopicMappingException.cs +++ b/OnTopic/Mapping/_exceptions/TopicMappingException.cs @@ -26,7 +26,7 @@ public class TopicMappingException : Exception { /// /// Initializes a new instance. /// - public TopicMappingException() : base() { } + public TopicMappingException() { } /// /// Initializes a new instance with a specific error message. diff --git a/OnTopic/Obsolete/Collections/NamedTopicCollection.cs b/OnTopic/Obsolete/Collections/NamedTopicCollection.cs index 8413f465..b46d1847 100644 --- a/OnTopic/Obsolete/Collections/NamedTopicCollection.cs +++ b/OnTopic/Obsolete/Collections/NamedTopicCollection.cs @@ -31,7 +31,7 @@ public class NamedTopicCollection: KeyedTopicCollection { /// /// Provides a name for the collection, used to identify different collections. /// Optionally seeds the collection with an optional list of topic references. - public NamedTopicCollection(string name = "", IEnumerable? topics = null) : base() { + public NamedTopicCollection(string name = "", IEnumerable? topics = null) { Name = name; if (topics is not null) { CopyTo([.. topics], 0); diff --git a/OnTopic/Obsolete/Repositories/DeleteEventArgs.cs b/OnTopic/Obsolete/Repositories/DeleteEventArgs.cs index a407181e..52e7ce87 100644 --- a/OnTopic/Obsolete/Repositories/DeleteEventArgs.cs +++ b/OnTopic/Obsolete/Repositories/DeleteEventArgs.cs @@ -23,7 +23,7 @@ public class DeleteEventArgs : EventArgs { /// Initializes a new instance of the class. /// /// The topic. - public DeleteEventArgs(Topic topic) : base() { + public DeleteEventArgs(Topic topic) { Topic = topic; } diff --git a/OnTopic/Repositories/TopicRepositoryDecorator.cs b/OnTopic/Repositories/TopicRepositoryDecorator.cs index ce431aea..4568e05d 100644 --- a/OnTopic/Repositories/TopicRepositoryDecorator.cs +++ b/OnTopic/Repositories/TopicRepositoryDecorator.cs @@ -36,7 +36,7 @@ public abstract class TopicRepositoryDecorator : ObservableTopicRepository { /// A concrete instance of an , which will be used for data access. /// /// A new instance of the . - protected TopicRepositoryDecorator(ITopicRepository topicRepository) : base() { + protected TopicRepositoryDecorator(ITopicRepository topicRepository) { /*-------------------------------------------------------------------------------------------------------------------------- | Validate input diff --git a/OnTopic/Repositories/_eventArgs/TopicEventArgs.cs b/OnTopic/Repositories/_eventArgs/TopicEventArgs.cs index 8179a751..90808b2c 100644 --- a/OnTopic/Repositories/_eventArgs/TopicEventArgs.cs +++ b/OnTopic/Repositories/_eventArgs/TopicEventArgs.cs @@ -29,7 +29,7 @@ public class TopicEventArgs : EventArgs { /// /// The being operated against. /// Whether or not descendants of the were also loaded. - public TopicEventArgs(Topic topic, bool isRecursive = true) : base() { + public TopicEventArgs(Topic topic, bool isRecursive = true) { /*-------------------------------------------------------------------------------------------------------------------------- | Vaidate parameters diff --git a/OnTopic/Repositories/_exceptions/ReferentialIntegrityException.cs b/OnTopic/Repositories/_exceptions/ReferentialIntegrityException.cs index accb963a..77ed5b35 100644 --- a/OnTopic/Repositories/_exceptions/ReferentialIntegrityException.cs +++ b/OnTopic/Repositories/_exceptions/ReferentialIntegrityException.cs @@ -26,7 +26,7 @@ public class ReferentialIntegrityException: TopicRepositoryException { /// /// Initializes a new instance. /// - public ReferentialIntegrityException() : base() { } + public ReferentialIntegrityException() { } /// /// Initializes a new instance based on a /// Initializes a new instance. /// - public TopicNotFoundException() : base() { } + public TopicNotFoundException() { } /// /// Initializes a new instance based on a missing topic ID. diff --git a/OnTopic/Repositories/_exceptions/TopicRepositoryException.cs b/OnTopic/Repositories/_exceptions/TopicRepositoryException.cs index 933bffba..5fd9ed43 100644 --- a/OnTopic/Repositories/_exceptions/TopicRepositoryException.cs +++ b/OnTopic/Repositories/_exceptions/TopicRepositoryException.cs @@ -30,7 +30,7 @@ public class TopicRepositoryException : DbException { /// /// Initializes a new instance. /// - public TopicRepositoryException() : base() { } + public TopicRepositoryException() { } /// /// Initializes a new instance with a specific error message. From 691f5b98242e61245fa469e692ef418a7a0da298 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Thu, 9 Jul 2026 00:27:29 -0700 Subject: [PATCH 123/337] Prefer implicit constructors if type known (cont.) This continues previous implementations (56379ac2, 5c6bd856, e05427ff), picking up some missing references. --- .../TrackedRecordCollection{TItem,TValue,TAttribute}.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/OnTopic/Collections/Specialized/TrackedRecordCollection{TItem,TValue,TAttribute}.cs b/OnTopic/Collections/Specialized/TrackedRecordCollection{TItem,TValue,TAttribute}.cs index cd0120c7..321f723c 100644 --- a/OnTopic/Collections/Specialized/TrackedRecordCollection{TItem,TValue,TAttribute}.cs +++ b/OnTopic/Collections/Specialized/TrackedRecordCollection{TItem,TValue,TAttribute}.cs @@ -476,7 +476,7 @@ internal void SetValue( | Create new item \-------------------------------------------------------------------------------------------------------------------------*/ else { - updatedItem = new TItem() { + updatedItem = new() { Key = key, Value = value, IsDirty = AssociatedTopic.IsNew || (markDirty ?? true), From f6bfb68800b21cf5872d689ae3012271e689d114 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Thu, 9 Jul 2026 00:32:39 -0700 Subject: [PATCH 124/337] Remove unused `using` statements --- .../ServiceCollectionExtensionsTests.cs | 2 +- .../Components/PageLevelNavigationViewComponentBase{T}.cs | 2 +- OnTopic.Data.Sql/Models/AttributeValuesDataTable.cs | 2 +- OnTopic.Tests/ViewModels/InitializedTopicViewModel.cs | 1 - .../_collections/TopicViewModelCollection{TItem}.cs | 1 - OnTopic/Attributes/AttributeCollection.cs | 2 +- OnTopic/Lookup/DynamicTopicLookupService.cs | 1 - OnTopic/Mapping/Internal/ItemConfiguration.cs | 1 - OnTopic/Repositories/ITopicBackingAccessor.cs | 1 - OnTopic/Topic.cs | 1 - 10 files changed, 4 insertions(+), 10 deletions(-) diff --git a/OnTopic.AspNetCore.Mvc.IntegrationTests/ServiceCollectionExtensionsTests.cs b/OnTopic.AspNetCore.Mvc.IntegrationTests/ServiceCollectionExtensionsTests.cs index 7ad5bf2a..57809f6a 100644 --- a/OnTopic.AspNetCore.Mvc.IntegrationTests/ServiceCollectionExtensionsTests.cs +++ b/OnTopic.AspNetCore.Mvc.IntegrationTests/ServiceCollectionExtensionsTests.cs @@ -3,7 +3,7 @@ | Client Ignia, LLC | Project Topics Library \=============================================================================================================================*/ -using System; + using System.Net; using Microsoft.AspNetCore.Routing; diff --git a/OnTopic.AspNetCore.Mvc/Components/PageLevelNavigationViewComponentBase{T}.cs b/OnTopic.AspNetCore.Mvc/Components/PageLevelNavigationViewComponentBase{T}.cs index d0390e67..8fa89438 100644 --- a/OnTopic.AspNetCore.Mvc/Components/PageLevelNavigationViewComponentBase{T}.cs +++ b/OnTopic.AspNetCore.Mvc/Components/PageLevelNavigationViewComponentBase{T}.cs @@ -3,7 +3,7 @@ | Client Ignia, LLC | Project Topics Library \=============================================================================================================================*/ -using System.Diagnostics.CodeAnalysis; + using OnTopic.AspNetCore.Mvc.Controllers; using OnTopic.AspNetCore.Mvc.Models; using OnTopic.Mapping.Hierarchical; diff --git a/OnTopic.Data.Sql/Models/AttributeValuesDataTable.cs b/OnTopic.Data.Sql/Models/AttributeValuesDataTable.cs index fd3d86cb..17f853ee 100644 --- a/OnTopic.Data.Sql/Models/AttributeValuesDataTable.cs +++ b/OnTopic.Data.Sql/Models/AttributeValuesDataTable.cs @@ -3,7 +3,7 @@ | Client Ignia, LLC | Project Topics Library \=============================================================================================================================*/ -using OnTopic.Attributes; + using OnTopic.Collections.Specialized; namespace OnTopic.Data.Sql.Models; diff --git a/OnTopic.Tests/ViewModels/InitializedTopicViewModel.cs b/OnTopic.Tests/ViewModels/InitializedTopicViewModel.cs index 68d1b229..4d26f104 100644 --- a/OnTopic.Tests/ViewModels/InitializedTopicViewModel.cs +++ b/OnTopic.Tests/ViewModels/InitializedTopicViewModel.cs @@ -3,7 +3,6 @@ | Client Ignia, LLC | Project Topics Library \=============================================================================================================================*/ -using System.ComponentModel; namespace OnTopic.Tests.ViewModels; diff --git a/OnTopic.ViewModels/_collections/TopicViewModelCollection{TItem}.cs b/OnTopic.ViewModels/_collections/TopicViewModelCollection{TItem}.cs index d7c39d5d..b7c1281c 100644 --- a/OnTopic.ViewModels/_collections/TopicViewModelCollection{TItem}.cs +++ b/OnTopic.ViewModels/_collections/TopicViewModelCollection{TItem}.cs @@ -4,7 +4,6 @@ | Project Topics Library \=============================================================================================================================*/ using System.Collections.ObjectModel; -using OnTopic.Internal.Diagnostics; namespace OnTopic.ViewModels; diff --git a/OnTopic/Attributes/AttributeCollection.cs b/OnTopic/Attributes/AttributeCollection.cs index 821527e6..6c96e536 100644 --- a/OnTopic/Attributes/AttributeCollection.cs +++ b/OnTopic/Attributes/AttributeCollection.cs @@ -3,7 +3,7 @@ | Client Ignia, LLC | Project Topics Library \=============================================================================================================================*/ -using System.Diagnostics.CodeAnalysis; + using OnTopic.Collections.Specialized; using OnTopic.Repositories; diff --git a/OnTopic/Lookup/DynamicTopicLookupService.cs b/OnTopic/Lookup/DynamicTopicLookupService.cs index 599a44c8..9385d3d5 100644 --- a/OnTopic/Lookup/DynamicTopicLookupService.cs +++ b/OnTopic/Lookup/DynamicTopicLookupService.cs @@ -3,7 +3,6 @@ | Client Ignia, LLC | Project Topics Library \=============================================================================================================================*/ -using OnTopic.Metadata; namespace OnTopic.Lookup; diff --git a/OnTopic/Mapping/Internal/ItemConfiguration.cs b/OnTopic/Mapping/Internal/ItemConfiguration.cs index 928ac588..6456caca 100644 --- a/OnTopic/Mapping/Internal/ItemConfiguration.cs +++ b/OnTopic/Mapping/Internal/ItemConfiguration.cs @@ -6,7 +6,6 @@ using System.Collections.ObjectModel; using System.ComponentModel; using System.Reflection; -using OnTopic.Collections.Specialized; using OnTopic.Internal.Reflection; using OnTopic.Mapping.Annotations; diff --git a/OnTopic/Repositories/ITopicBackingAccessor.cs b/OnTopic/Repositories/ITopicBackingAccessor.cs index 8de29d82..96698997 100644 --- a/OnTopic/Repositories/ITopicBackingAccessor.cs +++ b/OnTopic/Repositories/ITopicBackingAccessor.cs @@ -4,7 +4,6 @@ | Project Topics Library \=============================================================================================================================*/ using OnTopic.Associations; -using OnTopic.Attributes; using OnTopic.Collections; namespace OnTopic.Repositories; diff --git a/OnTopic/Topic.cs b/OnTopic/Topic.cs index 854f51c8..ca5fafd5 100644 --- a/OnTopic/Topic.cs +++ b/OnTopic/Topic.cs @@ -4,7 +4,6 @@ | Project Topics Library \=============================================================================================================================*/ using System.Collections.ObjectModel; -using System.Diagnostics.CodeAnalysis; using System.Globalization; using OnTopic.Associations; using OnTopic.Collections; From 13264caa2cca6f7673eec3ffb9b7e9e8dc32df52 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Thu, 9 Jul 2026 00:38:46 -0700 Subject: [PATCH 125/337] Removed implicit, default arguments --- OnTopic/Repositories/TopicRepositoryDecorator.cs | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/OnTopic/Repositories/TopicRepositoryDecorator.cs b/OnTopic/Repositories/TopicRepositoryDecorator.cs index 4568e05d..f5e84729 100644 --- a/OnTopic/Repositories/TopicRepositoryDecorator.cs +++ b/OnTopic/Repositories/TopicRepositoryDecorator.cs @@ -51,11 +51,11 @@ protected TopicRepositoryDecorator(ITopicRepository topicRepository) { /*-------------------------------------------------------------------------------------------------------------------------- | Subscribe to underlying events \-------------------------------------------------------------------------------------------------------------------------*/ - TopicRepository.TopicLoaded += (object? sender, TopicLoadEventArgs args) => OnTopicLoaded(args); - TopicRepository.TopicSaved += (object? sender, TopicSaveEventArgs args) => OnTopicSaved(args); - TopicRepository.TopicDeleted += (object? sender, TopicEventArgs args) => OnTopicDeleted(args); - TopicRepository.TopicMoved += (object? sender, TopicMoveEventArgs args) => OnTopicMoved(args); - TopicRepository.TopicRenamed += (object? sender, TopicRenameEventArgs args) => OnTopicRenamed(args); + TopicRepository.TopicLoaded += (_, args) => OnTopicLoaded(args); + TopicRepository.TopicSaved += (_, args) => OnTopicSaved(args); + TopicRepository.TopicDeleted += (_, args) => OnTopicDeleted(args); + TopicRepository.TopicMoved += (_, args) => OnTopicMoved(args); + TopicRepository.TopicRenamed += (_, args) => OnTopicRenamed(args); } From 5b293fd6dd563382d11d55b0589a63515f201747 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Thu, 9 Jul 2026 01:21:34 -0700 Subject: [PATCH 126/337] Fixed gap in "stamping" of `ITopicLoadResolver` This patches an important gap in the lazy-loading infrastructure (#111) where the `ITopicLoadResolver` wasn't "stamped" onto children loaded as part of `EnsureLoaded()`, and thus those themselves wouldn't be lazy loaded! (This points further to big gaps in our test cases, which remain something I want to audit further, given all of the changes.) --- OnTopic.Data.Sql/SqlTopicRepository.cs | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index f82a6163..1e7a7775 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -484,6 +484,16 @@ public virtual async Task EnsureLoaded(Topic topic, TopicPayload payload, Cancel throw new TopicRepositoryException($"Topic payload failed to load: '{exception.Message}'", exception); } + /*-------------------------------------------------------------------------------------------------------------------------- + | Stamp resolver on newly loaded children + >--------------------------------------------------------------------------------------------------------------------------- + | Children filled here, as opposed to the initial recursive Load(), are new Topic instances with no Resolver of their own. + | Without this, they would be unable to lazy-load their own payload. + \-------------------------------------------------------------------------------------------------------------------------*/ + if (payload.HasFlag(TopicPayload.Children)) { + StampResolver(topic); + } + /*-------------------------------------------------------------------------------------------------------------------------- | Mark confirmed payload as Loaded >--------------------------------------------------------------------------------------------------------------------------- From 27265c60ab6371b0558f30b3624211e254ee322c Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Thu, 9 Jul 2026 03:27:31 -0700 Subject: [PATCH 127/337] Remove unneceasary, implicit overloads, parameters Remove implicitly defined defaults that don't help in anyway of distinguishingly them apart. --- .../Annotations/RelationshipAttribute.cs | 2 +- OnTopic/Repositories/TopicRepository.cs | 36 ++++++++++--------- .../_eventArgs/TopicMoveEventArgs.cs | 2 +- .../_eventArgs/TopicRenameEventArgs.cs | 2 +- OnTopic/Topic.cs | 4 +-- 5 files changed, 24 insertions(+), 22 deletions(-) diff --git a/OnTopic/Obsolete/Mapping/Annotations/RelationshipAttribute.cs b/OnTopic/Obsolete/Mapping/Annotations/RelationshipAttribute.cs index ce324625..7e453fef 100644 --- a/OnTopic/Obsolete/Mapping/Annotations/RelationshipAttribute.cs +++ b/OnTopic/Obsolete/Mapping/Annotations/RelationshipAttribute.cs @@ -23,7 +23,7 @@ public sealed class RelationshipAttribute : Attribute { /// /// The key value of the collection associated with the current property. public RelationshipAttribute(string key) { - TopicFactory.ValidateKey(key, false); + TopicFactory.ValidateKey(key); Key = key; } diff --git a/OnTopic/Repositories/TopicRepository.cs b/OnTopic/Repositories/TopicRepository.cs index 509736d2..d0b0544b 100644 --- a/OnTopic/Repositories/TopicRepository.cs +++ b/OnTopic/Repositories/TopicRepository.cs @@ -20,11 +20,11 @@ namespace OnTopic.Repositories; /// /// /// The is a highly opinionated base implementation of . -/// In addition to validating parameters and raising events on , , and , it also provides a number of (protected) methods to -/// aid implementors in evaluating and parsing data, such as . It is recommended that all concrete implementations of that are responsible for -/// persisting data to a data store use this as a base class. +/// In addition to validating parameters and raising events on , , and , it also provides a number of (protected) +/// methods to aid implementors in evaluating and parsing data, such as . It is recommended that all concrete implementations of +/// that are responsible for persisting data to a data store use this as a base class. /// /// /// Implementations of which need to use different business logic, or do not need to @@ -127,14 +127,15 @@ protected ContentTypeDescriptorCollection SetContentTypeDescriptors(Topic? sourc /// /// By default, the method will load data from the /// concrete implementation of the 's data store. There are cases, however, where it may be - /// preferrable to instead load these topics from a local, in-memory source. Namely, when first instantiating a new - /// OnTopic database, and when saving modifications to existing content types. As such, the protected method is useful to call from when the topic graph being saved includes any new s. + /// preferable to instead load these topics from a local, in-memory source. Namely, when first instantiating a new OnTopic + /// database, and when saving modifications to existing content types. As such, the protected method is useful to call from when the topic graph being saved includes any new s. /// /// - /// The root of a topic graph to merge into the collection for . The code will process not only the root topic graph to merge into the collection for . The code will process not only the root , but also any descendents. /// /// @@ -252,7 +253,7 @@ public override async Task Rollback([ValidatedNotNull]Topic topic, DateTime vers /*-------------------------------------------------------------------------------------------------------------------------- | Save as new version \-------------------------------------------------------------------------------------------------------------------------*/ - await Save(topic, false).ConfigureAwait(false); + await Save(topic).ConfigureAwait(false); } @@ -473,9 +474,9 @@ _contentTypeDescriptors is not null && /// "ContentTypeDescriptor"/> and instances as appropriate, raising the , if needed, and recursing over children. The derived implementation of is then left to focus exclusively on the core logic of persisting the changes - /// to the individual to the underlying data store, and optionally updating its and , assuming is set to - /// true. + /// to the individual to the underlying data store, and optionally updating its and , assuming is set to + /// true. /// /// The source to save. /// The version to assign to the updates. @@ -903,8 +904,9 @@ private static bool IsAttributeDescriptor(Topic topic) => /// The determines where an attribute should be stored; the /// determines where an attribute was stored. If these two /// values are in conflict, that suggests the coniguration for has - /// changed since the attribute value was last saved. In that case, it should be treated as even though its value hasn't changed to ensure that its storage location is updated. + /// changed since the attribute value was last saved. In that case, it should be treated as even though its value hasn't changed to ensure that its storage location is + /// updated. /// /// /// If cannot be found then the is arbitrary attribute diff --git a/OnTopic/Repositories/_eventArgs/TopicMoveEventArgs.cs b/OnTopic/Repositories/_eventArgs/TopicMoveEventArgs.cs index 7f85faec..2114411e 100644 --- a/OnTopic/Repositories/_eventArgs/TopicMoveEventArgs.cs +++ b/OnTopic/Repositories/_eventArgs/TopicMoveEventArgs.cs @@ -40,7 +40,7 @@ public class TopicMoveEventArgs : TopicEventArgs { /// /// != /// - public TopicMoveEventArgs(Topic topic, Topic? source, Topic target, Topic? sibling = null): base(topic, true) { + public TopicMoveEventArgs(Topic topic, Topic? source, Topic target, Topic? sibling = null): base(topic) { /*-------------------------------------------------------------------------------------------------------------------------- | Vaidate parameters diff --git a/OnTopic/Repositories/_eventArgs/TopicRenameEventArgs.cs b/OnTopic/Repositories/_eventArgs/TopicRenameEventArgs.cs index f36543f5..c20aebbf 100644 --- a/OnTopic/Repositories/_eventArgs/TopicRenameEventArgs.cs +++ b/OnTopic/Repositories/_eventArgs/TopicRenameEventArgs.cs @@ -24,7 +24,7 @@ public class TopicRenameEventArgs : TopicEventArgs { /// The object associated with the rename event. /// The original key of the prior to being renamed. /// The new key of the after being renamed. - public TopicRenameEventArgs(Topic topic, string originalKey, string newKey): base(topic, true) { + public TopicRenameEventArgs(Topic topic, string originalKey, string newKey): base(topic) { /*-------------------------------------------------------------------------------------------------------------------------- | Vaidate parameters diff --git a/OnTopic/Topic.cs b/OnTopic/Topic.cs index ca5fafd5..e3df6177 100644 --- a/OnTopic/Topic.cs +++ b/OnTopic/Topic.cs @@ -63,7 +63,7 @@ public Topic(string key, string contentType, Topic? parent = null, int id = -1) \-------------------------------------------------------------------------------------------------------------------------*/ Attributes = new(this); IncomingRelationships = new(this, true); - _relationships = new(this, false); + _relationships = new(this); _references = new(this); VersionHistory = new(); @@ -724,7 +724,7 @@ public string GetWebPath() { \---------------------------------------------------------------------------------------------------------------------------*/ /// - public bool IsDirty() => IsDirty(false, false); + public bool IsDirty() => IsDirty(false); /// /// Determines if the topic is dirty, optionally checking and . From f93a982cd1b9bf9fd601299a47367b9cd951a828 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 10 Jul 2026 13:30:13 -0700 Subject: [PATCH 128/337] Established new `LazyLoadingTopicRepository` This sits between the `ObservableTopicRepository` and the other two base `ITopicRepository` implementations: `TopicRepository` (for persistence layer implementations) and `TopicRepositoryDecorator` (for decorators that relay to an underlying `TopicRepository` implementation). Currently, this does nothing, but it will provide a home for centralizing shared logic required to support the lazy-loading infrastructure (#111). The goal is to remove this from specific implementations so it can be better shared by all implementations. --- .../LazyLoadingTopicRepository.cs | 28 +++++++++++++++++++ OnTopic/Repositories/TopicRepository.cs | 2 +- .../Repositories/TopicRepositoryDecorator.cs | 2 +- 3 files changed, 30 insertions(+), 2 deletions(-) create mode 100644 OnTopic/Repositories/LazyLoadingTopicRepository.cs diff --git a/OnTopic/Repositories/LazyLoadingTopicRepository.cs b/OnTopic/Repositories/LazyLoadingTopicRepository.cs new file mode 100644 index 00000000..d776c86a --- /dev/null +++ b/OnTopic/Repositories/LazyLoadingTopicRepository.cs @@ -0,0 +1,28 @@ +/*============================================================================================================================== +| Author Ignia, LLC +| Client Ignia, LLC +| Project Topics Library +\=============================================================================================================================*/ +using OnTopic.Associations; + +namespace OnTopic.Repositories; + +/*============================================================================================================================== +| CLASS: LAZY LOADING TOPIC REPOSITORY +\-----------------------------------------------------------------------------------------------------------------------------*/ +/// +/// Provides an abstract base class for centralizing infrastructure for implementations of that +/// support lazy-loading, independent of the underlying persistence store. +/// +/// +/// This sits between , which offers only event handling, and the two families of +/// concrete base classes: , for implementations that persist +/// directly to a data store, and , for implementations that wrap another . Both need to stamp topics with an and resolve deferred +/// associations, but neither should be coupled to the other's specific concerns (e.g., 's +/// sealed Save(), Move(), and Delete() template methods, which +/// must remain free to override for delegation). +/// +public abstract class LazyLoadingTopicRepository : ObservableTopicRepository { + +} //Class \ No newline at end of file diff --git a/OnTopic/Repositories/TopicRepository.cs b/OnTopic/Repositories/TopicRepository.cs index d0b0544b..3e7a03ba 100644 --- a/OnTopic/Repositories/TopicRepository.cs +++ b/OnTopic/Repositories/TopicRepository.cs @@ -33,7 +33,7 @@ namespace OnTopic.Repositories; /// should instead derive from the . /// /// -public abstract class TopicRepository : ObservableTopicRepository { +public abstract class TopicRepository : LazyLoadingTopicRepository { /*============================================================================================================================ | PRIVATE VARIABLES diff --git a/OnTopic/Repositories/TopicRepositoryDecorator.cs b/OnTopic/Repositories/TopicRepositoryDecorator.cs index f5e84729..42acb9fc 100644 --- a/OnTopic/Repositories/TopicRepositoryDecorator.cs +++ b/OnTopic/Repositories/TopicRepositoryDecorator.cs @@ -23,7 +23,7 @@ namespace OnTopic.Repositories; /// can leave everything else as is. /// [ExcludeFromCodeCoverage] -public abstract class TopicRepositoryDecorator : ObservableTopicRepository { +public abstract class TopicRepositoryDecorator : LazyLoadingTopicRepository { /*============================================================================================================================ | CONSTRUCTOR From 70005a1aa067bfc5557a22f95fa70f9db379ff33 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 10 Jul 2026 13:41:08 -0700 Subject: [PATCH 129/337] Move `StampResolver()` to `LazyLoading` repository Moved the existing `StampResolver()` (2a1ce8e5) from the `ObservableTopicRepository` to the new `LazyLoadingTopicRepository` (f93a982c). This was placed in `ObservableTopicRepository` because it was the common ancestor of both e.g., `SqlTopicRepository` and `CachedTopicRepository`, but it really doesn't have anything to do with observability, which is precisely why I established the `LazyLoadingTopicRepository`. This is a non-breaking change; it's just moving the method up one level in the chain, but to what remains a common ancestor. --- .../LazyLoadingTopicRepository.cs | 45 +++++++++++++++++++ .../Repositories/ObservableTopicRepository.cs | 42 ----------------- 2 files changed, 45 insertions(+), 42 deletions(-) diff --git a/OnTopic/Repositories/LazyLoadingTopicRepository.cs b/OnTopic/Repositories/LazyLoadingTopicRepository.cs index d776c86a..bf67500d 100644 --- a/OnTopic/Repositories/LazyLoadingTopicRepository.cs +++ b/OnTopic/Repositories/LazyLoadingTopicRepository.cs @@ -25,4 +25,49 @@ namespace OnTopic.Repositories; /// public abstract class LazyLoadingTopicRepository : ObservableTopicRepository { + /*============================================================================================================================ + | METHOD: STAMP RESOLVER + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Stamps the supplied and its entire loaded graph with this repository as the , enabling each topic to populate deferred portions of itself on demand. + /// + /// + /// + /// Only stamps when the current repository implements . A passthrough decorator that is + /// not itself a resolver leaves any existing inner stamp intact, rather than overwriting it. + /// + /// + /// Recursion is gated on so that unloaded branches are not forced to load. + /// Since is an autoloading getter, recursing into it unconditionally would trigger a load + /// for every branch just to stamp it; the gate keeps this confined to what's already + /// present. + /// + /// + /// Call this method once on the root of a recently loaded or saved graph; it stamps every present topic in one pass. + /// + /// + /// The root of the topic graph to stamp. + protected void StampResolver(Topic? topic) { + + // Skip if the TopicRepository is not an ITopicLoadResolver, or if the topic doesn't exist + if (this is not ITopicLoadResolver resolver || topic is null) { + return; + } + + // Stamp the resolver on the topic + topic.Resolver = resolver; + + // If the children aren't yet loaded, don't bother with them yet + if (!topic.IsLoaded(TopicPayload.Children)) { + return; + } + + // Stamp any children (this is recursive, obviously!) + foreach (var child in topic.Children) { + StampResolver(child); + } + + } + } //Class \ No newline at end of file diff --git a/OnTopic/Repositories/ObservableTopicRepository.cs b/OnTopic/Repositories/ObservableTopicRepository.cs index 80afb844..986868a8 100644 --- a/OnTopic/Repositories/ObservableTopicRepository.cs +++ b/OnTopic/Repositories/ObservableTopicRepository.cs @@ -273,48 +273,6 @@ public event EventHandler? TopicRenamed { /// public abstract Task Delete(Topic topic, bool isRecursive = false); - /*============================================================================================================================ - | METHOD: STAMP RESOLVER - \---------------------------------------------------------------------------------------------------------------------------*/ - /// - /// Stamps the supplied and its entire loaded graph with this repository as the , enabling each topic to populate deferred portions of itself on demand. - /// - /// - /// - /// Only stamps when the current repository implements . A passthrough decorator that is - /// not itself a resolver leaves any existing inner stamp intact, rather than overwriting it. - /// - /// - /// Recursion is gated on so that unloaded branches are not force-loaded. - /// - /// - /// Call this method once on the root of a loaded or saved graph; it stamps every resident node in one pass. - /// - /// - /// The root of the topic graph to stamp. - protected void StampResolver(Topic? topic) { - - // Skip if the TopicRepository is not an ITopicLoadResolver, or if the topic doesn't exist - if (this is not ITopicLoadResolver resolver || topic is null) { - return; - } - - // Stamp the resolver on the topic - topic.Resolver = resolver; - - // If the children aren't yet loaded, don't bother with them yet - if (!topic.IsLoaded(TopicPayload.Children)) { - return; - } - - // Stamp any children (this is recursive, obviously!) - foreach (var child in topic.Children) { - StampResolver(child); - } - - } - /*============================================================================================================================ | METHOD: NORMALIZE TO UTC \---------------------------------------------------------------------------------------------------------------------------*/ From b787626bc20a9e0691af91b54016a8a88a9999a9 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 10 Jul 2026 13:47:19 -0700 Subject: [PATCH 130/337] Centralized `ResolveDeferredAssociations()` Moved the `private` `ResolveDeferredAssociations()` method from `CachedTopicRepository` to the new `LazyLoadingTopicRepository` (f93a982c) as a `protected` method. This complements the move of `StampResolver()` here (70005a1a) as part of an effort to centralize the lazy-loading infrastructure (#111) into a common home. While this was previously private, it was also functionality that _should_ be supported by _all_ lazy-loading `ITopicRepository` implementations, including e.g., `SqlTopicRepository`. Moving it here and making it public will later support that. --- OnTopic.Data.Caching/CachedTopicRepository.cs | 39 --------------- .../LazyLoadingTopicRepository.cs | 48 +++++++++++++++++++ 2 files changed, 48 insertions(+), 39 deletions(-) diff --git a/OnTopic.Data.Caching/CachedTopicRepository.cs b/OnTopic.Data.Caching/CachedTopicRepository.cs index 2f69a240..22f84597 100644 --- a/OnTopic.Data.Caching/CachedTopicRepository.cs +++ b/OnTopic.Data.Caching/CachedTopicRepository.cs @@ -391,45 +391,6 @@ protected override void OnTopicRenamed(TopicRenameEventArgs args) { /*============================================================================================================================ | METHODS: PRIVATE \---------------------------------------------------------------------------------------------------------------------------*/ - /// - /// Resolves any relationship and reference targets that were deferred by the underlying by - /// loading each through the cache layer's own Load(), which checks the index before falling through to the - /// underlying persistence store. Targets that cannot be found are treated as stale references to deleted topics and - /// discarded; the getter clears any remaining entries after this method returns. - /// - /// The topic whose deferred associations should be resolved. - /// - /// The payload flags that were requested; only and are acted upon. - /// - private async Task ResolveDeferredAssociations(Topic topic, TopicPayload payload, CancellationToken cancellationToken) { - - var rawTopic = (ITopicBackingAccessor)topic; - - // Resolve deferred relationship targets; unresolvable targets are treated as stale and discarded - if (payload.HasFlag(TopicPayload.Relationships) && rawTopic.Relationships.Deferred.Count > 0) { - foreach (var deferred in rawTopic.Relationships.Deferred.ToArray()) { - var target = await Load(deferred.TopicId).ConfigureAwait(false); - // SetValue removes the matching Deferred entry; stale entries are cleared by the Topic getter - if (target is not null) { - rawTopic.Relationships.SetValue(deferred.Key, target, markDirty: false); - } - } - } - - // Resolve deferred reference targets; unresolvable targets are treated as stale and discarded - if (payload.HasFlag(TopicPayload.References) && rawTopic.References.Deferred.Count > 0) { - foreach (var deferred in rawTopic.References.Deferred.ToArray()) { - var target = await Load(deferred.TopicId).ConfigureAwait(false); - // SetValue removes the matching Deferred entry; stale entries are cleared by the Topic getter - if (target is not null) { - rawTopic.References.SetValue(deferred.Key, target, markDirty: false); - } - } - } - - } - /// /// Removes stale _topicByKey entries for and its descendants by swapping the prefix for the current one, then reindexes the subtree under its current unique keys. diff --git a/OnTopic/Repositories/LazyLoadingTopicRepository.cs b/OnTopic/Repositories/LazyLoadingTopicRepository.cs index bf67500d..5ad520b2 100644 --- a/OnTopic/Repositories/LazyLoadingTopicRepository.cs +++ b/OnTopic/Repositories/LazyLoadingTopicRepository.cs @@ -25,6 +25,54 @@ namespace OnTopic.Repositories; /// public abstract class LazyLoadingTopicRepository : ObservableTopicRepository { + /*============================================================================================================================ + | METHOD: RESOLVE DEFERRED ASSOCIATIONS + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Resolves any relationship and reference targets that were deferred by the underlying data source by loading each + /// through this repository's own , so + /// implementations that cache or index resident topics can short-circuit the round-trip. Targets that cannot be found are + /// treated as stale references to deleted topics and discarded; the getter clears any remaining entries after this method returns. + /// + /// The topic whose deferred associations should be resolved. + /// + /// The payload flags that were requested; only and are acted upon. + /// + /// An optional token that can be used to cancel the operation. + protected async Task ResolveDeferredAssociations(Topic topic, TopicPayload payload, CancellationToken cancellationToken) { + + // Validate input + Contract.Requires(topic, nameof(topic)); + + // Cast topic to safely access backing fields + var rawTopic = (ITopicBackingAccessor)topic; + + // Resolve deferred relationship targets; unresolvable targets are treated as stale and discarded + if (payload.HasFlag(TopicPayload.Relationships) && rawTopic.Relationships.Deferred.Count > 0) { + foreach (var deferred in rawTopic.Relationships.Deferred.ToArray()) { + var target = await Load(deferred.TopicId).ConfigureAwait(false); + // SetValue removes the matching Deferred entry; stale entries are cleared by the Topic getter + if (target is not null) { + rawTopic.Relationships.SetValue(deferred.Key, target, markDirty: false); + } + } + } + + // Resolve deferred reference targets; unresolvable targets are treated as stale and discarded + if (payload.HasFlag(TopicPayload.References) && rawTopic.References.Deferred.Count > 0) { + foreach (var deferred in rawTopic.References.Deferred.ToArray()) { + var target = await Load(deferred.TopicId).ConfigureAwait(false); + // SetValue removes the matching Deferred entry; stale entries are cleared by the Topic getter + if (target is not null) { + rawTopic.References.SetValue(deferred.Key, target, markDirty: false); + } + } + } + + } + /*============================================================================================================================ | METHOD: STAMP RESOLVER \---------------------------------------------------------------------------------------------------------------------------*/ From 1935995ce2f6368768e8c3321bdc0fed9c91eabb Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 10 Jul 2026 14:50:10 -0700 Subject: [PATCH 131/337] Clear deferred in `ResolveDeferredAssociations()` In the previous commit, I centralized `ResolveDeferredAssociations()` (b787626b) so that it could be shared between multiple implementations of `ITopicRepository`. In this update, I tidy up the `ResolveDeferredAssociations()` to clean up after itself instead of relying on e.g., the corresponding getters on `Topic`, as had been expected in `CachedTopicRepository`. This not only centralizes the behavior, but also resolved a bug where deferred associations would have been cleared even if the `CachedTopicRepository` wasn't being used and, thus, no effort had actually been made to resolve the associations. I also made significant updates to the documentation to better reflect its current assumptions (e.g., removing references to underlying persistence store vs. cache, neither of which are relevant at this point). I also removed the otherwise unnecessary `Count` check. This contributes to #111. --- .../LazyLoadingTopicRepository.cs | 22 +++++++++++-------- OnTopic/Topic.cs | 2 -- 2 files changed, 13 insertions(+), 11 deletions(-) diff --git a/OnTopic/Repositories/LazyLoadingTopicRepository.cs b/OnTopic/Repositories/LazyLoadingTopicRepository.cs index 5ad520b2..d03c3232 100644 --- a/OnTopic/Repositories/LazyLoadingTopicRepository.cs +++ b/OnTopic/Repositories/LazyLoadingTopicRepository.cs @@ -29,12 +29,14 @@ public abstract class LazyLoadingTopicRepository : ObservableTopicRepository { | METHOD: RESOLVE DEFERRED ASSOCIATIONS \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Resolves any relationship and reference targets that were deferred by the underlying data source by loading each - /// through this repository's own , so - /// implementations that cache or index resident topics can short-circuit the round-trip. Targets that cannot be found are - /// treated as stale references to deleted topics and discarded; the getter clears any remaining entries after this method returns. + /// Resolves any relationship and reference targets that were deferred when loading each through this repository's own + /// . /// + /// + /// Targets that cannot be found after this are treated as stale references to deleted topics; this completed by clearing + /// the , resulting in the corresponding association collection to . + /// /// The topic whose deferred associations should be resolved. /// /// The payload flags that were requested; only and 0) { + if (payload.HasFlag(TopicPayload.Relationships)) { foreach (var deferred in rawTopic.Relationships.Deferred.ToArray()) { var target = await Load(deferred.TopicId).ConfigureAwait(false); - // SetValue removes the matching Deferred entry; stale entries are cleared by the Topic getter + // SetValue removes the matching Deferred entry; any left unresolved are cleared below if (target is not null) { rawTopic.Relationships.SetValue(deferred.Key, target, markDirty: false); } } + rawTopic.Relationships.Deferred.Clear(); } // Resolve deferred reference targets; unresolvable targets are treated as stale and discarded - if (payload.HasFlag(TopicPayload.References) && rawTopic.References.Deferred.Count > 0) { + if (payload.HasFlag(TopicPayload.References)) { foreach (var deferred in rawTopic.References.Deferred.ToArray()) { var target = await Load(deferred.TopicId).ConfigureAwait(false); - // SetValue removes the matching Deferred entry; stale entries are cleared by the Topic getter + // SetValue removes the matching Deferred entry; any left unresolved are cleared below if (target is not null) { rawTopic.References.SetValue(deferred.Key, target, markDirty: false); } } + rawTopic.References.Deferred.Clear(); } } diff --git a/OnTopic/Topic.cs b/OnTopic/Topic.cs index e3df6177..da77ef81 100644 --- a/OnTopic/Topic.cs +++ b/OnTopic/Topic.cs @@ -925,7 +925,6 @@ public TopicRelationshipMultiMap Relationships { get { if (_relationships.LoadState is LoadState.NotLoaded && Resolver is not null) { EnsureLoaded(TopicPayload.Relationships).GetAwaiter().GetResult(); - _relationships.Deferred.Clear(); } return _relationships; } @@ -946,7 +945,6 @@ public TopicReferenceCollection References { get { if (_references.LoadState is LoadState.NotLoaded && Resolver is not null) { EnsureLoaded(TopicPayload.References).GetAwaiter().GetResult(); - _references.Deferred.Clear(); } return _references; } From cf376a7fb273fd0f81656e5089bb71e3014755a0 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 10 Jul 2026 14:58:15 -0700 Subject: [PATCH 132/337] Implemented `ResolveDeferredAssociations()` in SQL MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Part of the motivation of centralizing `ResolveDeferredAssociations()` (b787626b, 1935995c) in the new `LazyLoadingTopicRepository` (f93a982c) was to allow that shared lazy-loading infrastructure (#111) to be shared among other `ITopicRepository` implementations, instead of it only being supported in `CachedTopicRepository`. This fulfills that promise by supporting it in `SqlTopicRepository` directly. This means topics exclusively stamped with `SqlTopicRepository` are still able to load their relationships and references—though they won't have the benefit of connecting them to cached version, so it'll be significantly slower. As part of this, I needed to patch the `CachedTopicRepository` to clear the `Relationships` and `References` flag from the `TopicPayload` being passed to the underlying `EnsureLoaded()` to make sure that the e.g., `SqlTopicRepository` wasn't duplicating or competing for the same work, leaving that exclusively to the `CachedTopicRepository`, which has the benefit of not only finding existing references in the cache, but also returning them quickly since they're indexed. --- OnTopic.Data.Caching/CachedTopicRepository.cs | 15 +++++++++++++-- OnTopic.Data.Sql/SqlTopicRepository.cs | 17 +++++++++++++---- 2 files changed, 26 insertions(+), 6 deletions(-) diff --git a/OnTopic.Data.Caching/CachedTopicRepository.cs b/OnTopic.Data.Caching/CachedTopicRepository.cs index 22f84597..6689f2a8 100644 --- a/OnTopic.Data.Caching/CachedTopicRepository.cs +++ b/OnTopic.Data.Caching/CachedTopicRepository.cs @@ -272,12 +272,23 @@ public virtual async Task EnsureLoaded(Topic topic, TopicPayload payload, Cancel /*-------------------------------------------------------------------------------------------------------------------------- | Delegate to the inner resolver; captures missing targets in the Deferred collections + >------------------------------------------------------------------------------------------------------------------------- + | Relationships and References are withheld from the inner delegation: This cache is the outermost resolver, so it alone + | is responsible for resolving deferred association targets, via its own Load()—which checks the flat index before + | falling through to the inner repository. If the inner repository (e.g., SqlTopicRepository) were also asked to resolve + | them, it would do so via its own, non-cache-aware Load(), producing a duplicate Topic instance for any target that's + | already present in this cache. \-------------------------------------------------------------------------------------------------------------------------*/ if (TopicRepository is ITopicLoadResolver resolver) { - await resolver.EnsureLoaded(topic, payload, cancellationToken).ConfigureAwait(false); + var innerPayload = payload & ~(TopicPayload.Relationships | TopicPayload.References); + if (innerPayload is not TopicPayload.None) { + await resolver.EnsureLoaded(topic, innerPayload, cancellationToken).ConfigureAwait(false); + } } - // Resolve any deferred relationship/reference targets through the cache layer + /*-------------------------------------------------------------------------------------------------------------------------- + | Resolve any relationship and reference targets via the cache layer + \-------------------------------------------------------------------------------------------------------------------------*/ await ResolveDeferredAssociations(topic, payload, cancellationToken).ConfigureAwait(false); // Update flat index and stamp resolver for any newly loaded children diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index 1e7a7775..e2c8fcaf 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -406,8 +406,17 @@ public virtual async Task EnsureLoaded(Topic topic, TopicPayload payload, Cancel return; } - // Relationships and References themselves not by SqlTopicRepository; exit early if that's all that's pending so we don't - // open a database connection unnecessarily + /*-------------------------------------------------------------------------------------------------------------------------- + | Resolve any relationship and reference targets first + \-------------------------------------------------------------------------------------------------------------------------*/ + // Resolve any deferred relationship/reference targets by loading each individually; these were left unresolved by the + // initial Load() because their targets weren't part of that call's ascendant/descendant scope, and couldn't be found in the + // referenceTopic, if provided. + if (payload.HasFlag(TopicPayload.Relationships) || payload.HasFlag(TopicPayload.References)) { + await ResolveDeferredAssociations(topic, payload, cancellationToken).ConfigureAwait(false); + } + + // Exit early if nothing else is pending so we don't open a database connection unnecessarily if (!payload.HasFlag(TopicPayload.Children) && !payload.HasFlag(TopicPayload.ExtendedAttributes)) { return; } @@ -467,13 +476,13 @@ public virtual async Task EnsureLoaded(Topic topic, TopicPayload payload, Cancel rawTopic.References.Deferred.Clear(); } - // Relationships + // Relationships (will be empty, unless loading children) await reader.NextResultAsync(cancellationToken).ConfigureAwait(false); while (await reader.ReadAsync(cancellationToken).ConfigureAwait(false)) { reader.SetRelationships(topics, markDirty: false); } - // References + // References (will be empty, unless loading children) await reader.NextResultAsync(cancellationToken).ConfigureAwait(false); while (await reader.ReadAsync(cancellationToken).ConfigureAwait(false)) { reader.SetReferences(topics, markDirty: false); From 4caa4b496904f256a19cfa57d159033a82170a41 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 10 Jul 2026 15:06:38 -0700 Subject: [PATCH 133/337] FIre `TopicLoaded` event for children in SQL When `SqlTopicRepository.Load()` successfully loads topics from a persistence store, it fires the `TopicLoaded` event via the `OnTopicLoaded()` method. When `SqlTopicRepository.EnsureLoaded()` loads associations in response to the `TopicPayload.Relationships` or `TopicPayload.References`, it delegates to `Load()`, and thus fires the `TopicLoaded` event as well (cf376a7f). When `SqlTopicRepository.EnsureLoaded()` loads children in response to `TopicPayload.Children`, however, it wasn't firing the `TopicLoaded` event, because it didn't favor using `Load()` for technical reasons. That's an internal implementation detail that callers shouldn't be aware of. Nevertheless, callers would rightfully expect that loading child topics from the persistence store and placing them into the topic graph would trigger a `TopicLoaded` event, no different than loading associated topics from the persistence store and placing them into the topic graph. Given that, I'm adding that functionality to the `SqlTopicRepository.EnsureLoaded()` method. This will contribute to future work related to #111. --- OnTopic.Data.Sql/SqlTopicRepository.cs | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index e2c8fcaf..49887bd0 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -494,13 +494,17 @@ public virtual async Task EnsureLoaded(Topic topic, TopicPayload payload, Cancel } /*-------------------------------------------------------------------------------------------------------------------------- - | Stamp resolver on newly loaded children + | Raise event for each newly loaded child, and stamp resolver >--------------------------------------------------------------------------------------------------------------------------- - | Children filled here, as opposed to the initial recursive Load(), are new Topic instances with no Resolver of their own. - | Without this, they would be unable to lazy-load their own payload. + | Children filled here, as opposed to the initial recursive Load(), are new Topic instances introduced to the graph for the + | first time—conceptually the same as being loaded via Load(), just via a different entry point. This also stamps each one + | with a Resolver, without which they would be unable to lazy-load their own payload. \-------------------------------------------------------------------------------------------------------------------------*/ if (payload.HasFlag(TopicPayload.Children)) { StampResolver(topic); + foreach (var child in topic.Children) { + OnTopicLoaded(new(child, isRecursive: false)); + } } /*-------------------------------------------------------------------------------------------------------------------------- From cd21597454e5e7f22de1e16960ad431fb864691f Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 10 Jul 2026 17:02:05 -0700 Subject: [PATCH 134/337] Move stamping w/in `LazyLoadingTopicRepository` Since the new `LazyLoadingTopicRepository` sits on top of `ObservableTopicRepository` (f93a982c), and since both `Load()` and `EnsureLoaded(TopicPayload.Children)` now fire the `TopicLoaded` event (4caa4b49), we can handle the `StampResolver()` calls via the `TopicLoaded` and `TopicSaved` events internally within the `LazyLoadingTopicRepository`, making consumers completely unaware of the stamping process, outside of the `Topic` (which obviously must have the internal `Resolver` property that gets stamped; 819e3735, 6cd4e80d). This is a significant improvement in the lazy-loading infrastructure (#111) which previously required all implementers to be aware of the stamping process, and to orchestrate when that happened. --- OnTopic.Data.Caching/CachedTopicRepository.cs | 19 ++------- OnTopic.Data.Sql/SqlTopicRepository.cs | 16 +------ OnTopic.TestDoubles/StubTopicRepository.cs | 21 ---------- .../LazyLoadingTopicRepository.cs | 42 ++++++++++++++++++- OnTopic/Repositories/TopicRepository.cs | 5 --- .../Repositories/TopicRepositoryDecorator.cs | 5 +-- OnTopic/Topic.cs | 5 ++- 7 files changed, 51 insertions(+), 62 deletions(-) diff --git a/OnTopic.Data.Caching/CachedTopicRepository.cs b/OnTopic.Data.Caching/CachedTopicRepository.cs index 6689f2a8..538ef814 100644 --- a/OnTopic.Data.Caching/CachedTopicRepository.cs +++ b/OnTopic.Data.Caching/CachedTopicRepository.cs @@ -76,11 +76,6 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos IndexTopic(topic); } - /*-------------------------------------------------------------------------------------------------------------------------- - | Stamp resolver on seeded graph - \-------------------------------------------------------------------------------------------------------------------------*/ - StampResolver(_cache); - } /*============================================================================================================================ @@ -242,10 +237,7 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos /*-------------------------------------------------------------------------------------------------------------------------- | Return appropriate topic \-------------------------------------------------------------------------------------------------------------------------*/ - var topic = await TopicRepository.Load(topicId, version, referenceTopic ?? _cache) - .ConfigureAwait(false); - StampResolver(topic); - return topic; + return await TopicRepository.Load(topicId, version, referenceTopic ?? _cache).ConfigureAwait(false); } @@ -291,15 +283,14 @@ public virtual async Task EnsureLoaded(Topic topic, TopicPayload payload, Cancel \-------------------------------------------------------------------------------------------------------------------------*/ await ResolveDeferredAssociations(topic, payload, cancellationToken).ConfigureAwait(false); - // Update flat index and stamp resolver for any newly loaded children if (payload.HasFlag(TopicPayload.Children)) { lock (_syncLock) { foreach (var child in topic.Children) { IndexTopic(child); } } - StampResolver(topic); } + // Update flat index for any newly loaded children } @@ -457,8 +448,7 @@ private void IndexTopic(Topic topic) { /// /// The chain is walked from the leaf toward the root. At the first ancestor already present in _topicById /// (typically Root), the new node above it is discarded and its child is reparented to the cached object, which - /// attaches it to the existing graph. All new nodes below that boundary are indexed and stamped with the resolver so - /// their own can lazy-load on demand. + /// attaches it to the existing graph. All new nodes below that boundary are indexed here. /// /// /// The leaf topic returned from the underlying load, already part of an ancestor chain. @@ -489,11 +479,10 @@ private void MergeIntoCache(Topic loaded) { } } - // Index the new topic and stamp it with the resolver for future lazy fills + // Index the new topic lock (_syncLock) { IndexTopic(node); } - StampResolver(node); } diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index 49887bd0..5f81301a 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -184,11 +184,6 @@ public SqlTopicRepository(string connectionString) { \-------------------------------------------------------------------------------------------------------------------------*/ base.SetContentTypeDescriptors(topic); - /*-------------------------------------------------------------------------------------------------------------------------- - | Stamp resolver - \-------------------------------------------------------------------------------------------------------------------------*/ - StampResolver(topic); - /*-------------------------------------------------------------------------------------------------------------------------- | Raise event \-------------------------------------------------------------------------------------------------------------------------*/ @@ -307,11 +302,6 @@ public SqlTopicRepository(string connectionString) { rawTopic.Attributes.Remove(attribute.Key); } - /*-------------------------------------------------------------------------------------------------------------------------- - | Stamp resolver - \-------------------------------------------------------------------------------------------------------------------------*/ - StampResolver(topic); - /*-------------------------------------------------------------------------------------------------------------------------- | Raise event \-------------------------------------------------------------------------------------------------------------------------*/ @@ -494,14 +484,12 @@ public virtual async Task EnsureLoaded(Topic topic, TopicPayload payload, Cancel } /*-------------------------------------------------------------------------------------------------------------------------- - | Raise event for each newly loaded child, and stamp resolver + | Raise event for each newly loaded child >--------------------------------------------------------------------------------------------------------------------------- | Children filled here, as opposed to the initial recursive Load(), are new Topic instances introduced to the graph for the - | first time—conceptually the same as being loaded via Load(), just via a different entry point. This also stamps each one - | with a Resolver, without which they would be unable to lazy-load their own payload. + | first time—conceptually the same as being loaded via Load(), just via a different entry point. \-------------------------------------------------------------------------------------------------------------------------*/ if (payload.HasFlag(TopicPayload.Children)) { - StampResolver(topic); foreach (var child in topic.Children) { OnTopicLoaded(new(child, isRecursive: false)); } diff --git a/OnTopic.TestDoubles/StubTopicRepository.cs b/OnTopic.TestDoubles/StubTopicRepository.cs index d42c6527..64ee2daf 100644 --- a/OnTopic.TestDoubles/StubTopicRepository.cs +++ b/OnTopic.TestDoubles/StubTopicRepository.cs @@ -63,13 +63,6 @@ public StubTopicRepository() { topic = _cache.FindFirst(t => t.Id.Equals(topicId)); } - /*-------------------------------------------------------------------------------------------------------------------------- - | Stamp resolver - \-------------------------------------------------------------------------------------------------------------------------*/ - if (topic is not null) { - StampResolver(topic); - } - /*-------------------------------------------------------------------------------------------------------------------------- | Raise event \-------------------------------------------------------------------------------------------------------------------------*/ @@ -104,13 +97,6 @@ public StubTopicRepository() { \-------------------------------------------------------------------------------------------------------------------------*/ var topic = _cache.GetByUniqueKey(uniqueKey); - /*-------------------------------------------------------------------------------------------------------------------------- - | Stamp resolver - \-------------------------------------------------------------------------------------------------------------------------*/ - if (topic is not null) { - StampResolver(topic); - } - /*-------------------------------------------------------------------------------------------------------------------------- | Raise event \-------------------------------------------------------------------------------------------------------------------------*/ @@ -146,13 +132,6 @@ public StubTopicRepository() { topic = _cache.FindFirst(t => t.Id.Equals(topicId)); } - /*-------------------------------------------------------------------------------------------------------------------------- - | Stamp resolver - \-------------------------------------------------------------------------------------------------------------------------*/ - if (topic is not null) { - StampResolver(topic); - } - /*-------------------------------------------------------------------------------------------------------------------------- | Raise event \-------------------------------------------------------------------------------------------------------------------------*/ diff --git a/OnTopic/Repositories/LazyLoadingTopicRepository.cs b/OnTopic/Repositories/LazyLoadingTopicRepository.cs index d03c3232..e44566a2 100644 --- a/OnTopic/Repositories/LazyLoadingTopicRepository.cs +++ b/OnTopic/Repositories/LazyLoadingTopicRepository.cs @@ -25,6 +25,46 @@ namespace OnTopic.Repositories; /// public abstract class LazyLoadingTopicRepository : ObservableTopicRepository { + /*============================================================================================================================ + | METHOD: ON TOPIC LOADED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// + /// + /// Stamps the from the , and any descendants attached to it, + /// via and before raising the event, so the + /// resolver gets stamped without the resolvers needing to be aware of it. + /// + /// + /// fires only for the requested topic, never individually for any descendants + /// pulled in alongside it, so this handles both. + /// + /// + /// Stamping ahead of the base call is load-bearing: subscribes to its inner in its constructor, so raising the event here synchronously re-enters this + /// method on any outer decorators before this call returns, letting the outer's stamp take precedence over inner ones. + /// + /// + protected override void OnTopicLoaded(TopicLoadEventArgs args) { + Contract.Requires(args, nameof(args)); + StampResolver(args.Topic); + base.OnTopicLoaded(args); + } + + /*============================================================================================================================ + | METHOD: ON TOPIC SAVED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// + /// Stamps the from the via + /// before raising the event for the same reason and via the same method as . + /// + protected override void OnTopicSaved(TopicSaveEventArgs args) { + Contract.Requires(args, nameof(args)); + StampResolver(args.Topic); + base.OnTopicSaved(args); + } + /*============================================================================================================================ | METHOD: RESOLVE DEFERRED ASSOCIATIONS \---------------------------------------------------------------------------------------------------------------------------*/ @@ -100,7 +140,7 @@ protected async Task ResolveDeferredAssociations(Topic topic, TopicPayload paylo /// /// /// The root of the topic graph to stamp. - protected void StampResolver(Topic? topic) { + private void StampResolver(Topic? topic) { // Skip if the TopicRepository is not an ITopicLoadResolver, or if the topic doesn't exist if (this is not ITopicLoadResolver resolver || topic is null) { diff --git a/OnTopic/Repositories/TopicRepository.cs b/OnTopic/Repositories/TopicRepository.cs index 3e7a03ba..2b028d0f 100644 --- a/OnTopic/Repositories/TopicRepository.cs +++ b/OnTopic/Repositories/TopicRepository.cs @@ -304,11 +304,6 @@ public override sealed async Task Save([ValidatedNotNull] Topic topic, bool isRe ); } - /*-------------------------------------------------------------------------------------------------------------------------- - | Stamp resolver - \-------------------------------------------------------------------------------------------------------------------------*/ - StampResolver(topic); - /*-------------------------------------------------------------------------------------------------------------------------- | Raise event \-------------------------------------------------------------------------------------------------------------------------*/ diff --git a/OnTopic/Repositories/TopicRepositoryDecorator.cs b/OnTopic/Repositories/TopicRepositoryDecorator.cs index 42acb9fc..88f16aed 100644 --- a/OnTopic/Repositories/TopicRepositoryDecorator.cs +++ b/OnTopic/Repositories/TopicRepositoryDecorator.cs @@ -121,10 +121,7 @@ protected TopicRepositoryDecorator(ITopicRepository topicRepository) { | METHOD: SAVE \---------------------------------------------------------------------------------------------------------------------------*/ /// - public override async Task Save(Topic topic, bool isRecursive = false) { - await TopicRepository.Save(topic, isRecursive).ConfigureAwait(false); - StampResolver(topic); - } + public override Task Save(Topic topic, bool isRecursive = false) => TopicRepository.Save(topic, isRecursive); /*============================================================================================================================ | METHOD: MOVE diff --git a/OnTopic/Topic.cs b/OnTopic/Topic.cs index da77ef81..b31c09f5 100644 --- a/OnTopic/Topic.cs +++ b/OnTopic/Topic.cs @@ -578,8 +578,9 @@ public DateTime LastModified { | PROPERTY: RESOLVER \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Provides an internal reference to the used to lazy load collections on request. This is - /// applied via the method. + /// Provides an internal reference to the used to lazy load collections on request. This + /// is stamped by the with whichever + /// most recently loaded or saved this topic. /// internal ITopicLoadResolver? Resolver { get; set; } From 7ad38df9c9965ca31646984f54b1388312e74f4b Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 10 Jul 2026 17:17:54 -0700 Subject: [PATCH 135/337] Manage index via `OnTopicLoaded()` This mirrors the approach taken to maintain the `StampResolver()` (cd215974), but is implemented in the `CachedTopicRepository` to help manage the index (22161b12, f50cd8ba). This also maps to the approach already taken for managing the index when it comes to saves, moves, renames, and deletions (d5084085); this just extends that approach to also cover loading. --- OnTopic.Data.Caching/CachedTopicRepository.cs | 39 ++++++++++++++----- 1 file changed, 30 insertions(+), 9 deletions(-) diff --git a/OnTopic.Data.Caching/CachedTopicRepository.cs b/OnTopic.Data.Caching/CachedTopicRepository.cs index 538ef814..f5d561b1 100644 --- a/OnTopic.Data.Caching/CachedTopicRepository.cs +++ b/OnTopic.Data.Caching/CachedTopicRepository.cs @@ -3,7 +3,6 @@ | Client Ignia, LLC | Project Topics Library \=============================================================================================================================*/ -using OnTopic.Associations; using OnTopic.Internal.Diagnostics; using OnTopic.Querying; using OnTopic.Repositories; @@ -283,13 +282,6 @@ public virtual async Task EnsureLoaded(Topic topic, TopicPayload payload, Cancel \-------------------------------------------------------------------------------------------------------------------------*/ await ResolveDeferredAssociations(topic, payload, cancellationToken).ConfigureAwait(false); - if (payload.HasFlag(TopicPayload.Children)) { - lock (_syncLock) { - foreach (var child in topic.Children) { - IndexTopic(child); - } - } - } // Update flat index for any newly loaded children } @@ -300,7 +292,36 @@ public virtual async Task EnsureLoaded(Topic topic, TopicPayload payload, Cancel /// /// - /// Adds newly-created topics to the flat index. When the save is recursive, all resident descendants are indexed as well, + /// Adds the newly loaded topic to the index and clears any entries previously known to be missing, so a topic that was + /// missing on an earlier lookup can be found now. This automatically indexes any descendants loaded alongside the topic, + /// for cases where the isRecursive parameter was specified on . + /// Ascendants pulled in alongside it are handled separately by , since only one event fires per load, for the requested topic, not each ascendant. + /// + protected override void OnTopicLoaded(TopicLoadEventArgs args) { + + // Setup + Contract.Requires(args); + base.OnTopicLoaded(args); + + // Index the loaded topic and any descendants that came back attached; FindAll() is lazy-safe and naturally returns just + // the topic itself when nothing further is present, so this is correct whether or not the load was recursive + lock (_syncLock) { + foreach (var topic in args.Topic.FindAll()) { + if (_topicIdIndex.ContainsKey(topic.Id)) { + continue; + } + IndexTopic(topic); + _absentTopicIdIndex.Remove(topic.Id); + _absentUniqueKeyIndex.Remove(topic.GetUniqueKey()); + } + } + + } + + /// + /// + /// Adds newly created topics to the flat index. When the save is recursive, all present descendants are indexed as well, /// since only one event fires for the root of a recursive save. Also clears any /// entries known to be missing so that a previously missing ID or key that is now created can be found on subsequent /// lookups. From 1853602aa44a2d0b5069b1a469e21d1cc8d77133 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 10 Jul 2026 17:25:46 -0700 Subject: [PATCH 136/337] Ensure cache misses called with same arguments For some reason, when I added support for `CachedTopicRepository.Load()` falling back to the underlying `TopicRepository.Load()` on cache misses (599c5bef), I hard-coded the `referenceTopic` to `null` and `isRecursive` to `false`. This makes no sense. This should honor and return exactly what the caller requested, regardless of the source of the content. As a result, this now passes along --- OnTopic.Data.Caching/CachedTopicRepository.cs | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/OnTopic.Data.Caching/CachedTopicRepository.cs b/OnTopic.Data.Caching/CachedTopicRepository.cs index f5d561b1..20f43f2d 100644 --- a/OnTopic.Data.Caching/CachedTopicRepository.cs +++ b/OnTopic.Data.Caching/CachedTopicRepository.cs @@ -122,8 +122,9 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos /*-------------------------------------------------------------------------------------------------------------------------- | On miss: Load with ancestors and merge result into the live graph \-------------------------------------------------------------------------------------------------------------------------*/ - var loaded = await TopicRepository.Load(topicId, referenceTopic: null, isRecursive: false) - .ConfigureAwait(false); + var loaded = await TopicRepository + .Load(topicId, referenceTopic, isRecursive, payload) + .ConfigureAwait(false); // If it's missing, populate the appropriate index so we don't try loading it again if (loaded is null) { @@ -196,8 +197,9 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos /*-------------------------------------------------------------------------------------------------------------------------- | On miss: Load with ancestors and merge result into the live graph \-------------------------------------------------------------------------------------------------------------------------*/ - var loaded = await TopicRepository.Load(uniqueKey, referenceTopic: null, isRecursive: false) - .ConfigureAwait(false); + var loaded = await TopicRepository + .Load(uniqueKey, referenceTopic, isRecursive, payload) + .ConfigureAwait(false); if (loaded is null) { lock (_syncLock) { From 43ba647fbbd685dd27d00b667950a9e58fdad122 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 10 Jul 2026 17:26:35 -0700 Subject: [PATCH 137/337] Reformat `Load()` calls This matches the formatting used in the previous commit (1853602a) and is better than having the `.GetAwaiter()` hanging awkwardly with inconsistent indentation. --- OnTopic.Data.Caching/CachedTopicRepository.cs | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/OnTopic.Data.Caching/CachedTopicRepository.cs b/OnTopic.Data.Caching/CachedTopicRepository.cs index 20f43f2d..6a637907 100644 --- a/OnTopic.Data.Caching/CachedTopicRepository.cs +++ b/OnTopic.Data.Caching/CachedTopicRepository.cs @@ -48,8 +48,10 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos /*-------------------------------------------------------------------------------------------------------------------------- | Seed root topic (without descendants) \-------------------------------------------------------------------------------------------------------------------------*/ - var rootTopic = TopicRepository.Load("Root", referenceTopic: null, isRecursive: false) - .GetAwaiter().GetResult(); + var rootTopic = TopicRepository + .Load("Root", referenceTopic: null, isRecursive: false) + .GetAwaiter() + .GetResult(); Contract.Assume( rootTopic, @@ -65,8 +67,10 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos /*-------------------------------------------------------------------------------------------------------------------------- | Eager-load Root:Configuration subtree (required for content-type descriptor resolution) \-------------------------------------------------------------------------------------------------------------------------*/ - TopicRepository.Load("Root:Configuration", referenceTopic: _cache, isRecursive: true, payload: TopicPayload.All) - .GetAwaiter().GetResult(); + TopicRepository + .Load("Root:Configuration", referenceTopic: _cache, isRecursive: true, payload: TopicPayload.All) + .GetAwaiter() + .GetResult(); /*-------------------------------------------------------------------------------------------------------------------------- | Populate flat index from seeded topics From 29969d1c5921d07973ca90d14e03816a22e4e4d6 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 10 Jul 2026 17:55:10 -0700 Subject: [PATCH 138/337] Introduce and wire-up `StampAscendants()` Since I added the ability to load ascendants in order to merge one-off loads (such as associations) into a sparse topic graph (de60afb4, 2e4b1251, c33f4a43), I also need to make sure that ascendants are stamped with the resolver on `Load()`. The `StampAscendants()` handles that, and is incorporated into the `OnLoaded()` event alongside the call to `StampResolver()` (cd215974, 70005a1a). The patches a gap in the lazy-loading infrastructure (#111). --- .../LazyLoadingTopicRepository.cs | 41 +++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/OnTopic/Repositories/LazyLoadingTopicRepository.cs b/OnTopic/Repositories/LazyLoadingTopicRepository.cs index e44566a2..d96565de 100644 --- a/OnTopic/Repositories/LazyLoadingTopicRepository.cs +++ b/OnTopic/Repositories/LazyLoadingTopicRepository.cs @@ -48,6 +48,7 @@ public abstract class LazyLoadingTopicRepository : ObservableTopicRepository { protected override void OnTopicLoaded(TopicLoadEventArgs args) { Contract.Requires(args, nameof(args)); StampResolver(args.Topic); + StampAscendants(args.Topic.Parent); base.OnTopicLoaded(args); } @@ -162,4 +163,44 @@ private void StampResolver(Topic? topic) { } + /*============================================================================================================================ + | METHOD: STAMP ASCENDANTS + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Walks a 's chain, stamping each with this repository as the , so an ascendant that was never individually loaded can still lazy-load its own deferred + /// payload. + /// + /// + /// + /// Stops as soon as it reaches an ascendant already stamped by this exact resolver instance, on the assumption that its + /// own ascendants were already walked and stamped at that time. Comparing by instance, rather than merely checking for a + /// non-null , matters when this method runs as part of a decorated stack: An outer + /// decorator's pass must not stop early just because an inner repository already stamped the chain with itself. + /// + /// + /// In practice, this only short-circuits repeat calls against the same, undecorated resolver instance (e.g., a bare + /// loading many topics over its lifetime that share ascendant branches). When wrapped by a + /// , the inner and outer passes stamp with different instances on every call, so + /// neither ever finds a match from the other, and thus each pass walks the full chain to the root every time. That's + /// harmless, just not a savings there. + /// + /// + /// + /// The topic at which to start walking (typically a loaded topic's ). + /// + private void StampAscendants(Topic? topic) { + + // Skip if the current repository is not an ITopicLoadResolver + if (this is not ITopicLoadResolver resolver) { + return; + } + + // Walk and stamp each ascendant, stopping once this resolver has already stamped one + for (var ascendant = topic; ascendant is not null && ascendant.Resolver != resolver; ascendant = ascendant.Parent) { + ascendant.Resolver = resolver; + } + + } + } //Class \ No newline at end of file From 60276b84123a79cd4695ce20d0366f264171d167 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 10 Jul 2026 17:58:47 -0700 Subject: [PATCH 139/337] Added test for the new `StampAscendants()` This introduces a new unit test for ensuring that ascendants are stamped with the resolver via the new `StampAscendants()` method (29969d1c) when loaded via `Load()`. This contributes to testing of the lazy-loading infrastructure (#111). --- OnTopic.Tests/TopicRepositoryBaseTest.cs | 32 ++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/OnTopic.Tests/TopicRepositoryBaseTest.cs b/OnTopic.Tests/TopicRepositoryBaseTest.cs index 7dd8d608..b9a6b2cb 100644 --- a/OnTopic.Tests/TopicRepositoryBaseTest.cs +++ b/OnTopic.Tests/TopicRepositoryBaseTest.cs @@ -1481,6 +1481,38 @@ public async Task EnsureLoaded_Relationships_AlreadyLoaded_SkipsFill() { } + /*============================================================================================================================ + | TEST: LOAD: WITH ASCENDANTS: STAMPS ASCENDANT RESOLVERS + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Calls on a standalone instance—i.e., not + /// wrapped by , and never itself passed to Load() before—for a deeply nested + /// topic, and confirms that an ascendant is nonetheless stamped with an , so its own + /// deferred payload can still be lazy-loaded. + /// + /// + /// Uses a fresh rather than the shared field: The latter + /// is wrapped by in the constructor, whose own seeding recursively stamps the entire + /// (eagerly loaded) stub tree via , which would mask whether ascendant stamping actually comes + /// from this test's Load() call. + /// + [Fact] + public async Task Load_WithAscendants_StampsAscendantResolvers() { + + // Arrange: use a standalone repository, never wrapped by CachedTopicRepository + var topicRepository = new StubTopicRepository(); + + // Act: load a deeply nested topic + var topic = await topicRepository.Load("Root:Web:Web_3:Web_3_1:Web_3_1_0"); + + // An ascendant that was never itself the target of a Load() call is still stamped + var ascendant = topic?.Parent?.Parent; + + Assert.NotNull(ascendant); + Assert.NotNull(ascendant?.Resolver); + + } + /*============================================================================================================================ | TEST: MOVE: SAME LOCATION: EVENT NOT RAISED \---------------------------------------------------------------------------------------------------------------------------*/ From b815da7e086c8ef29e8f75a7ce77834e9349ff03 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 10 Jul 2026 17:59:55 -0700 Subject: [PATCH 140/337] Tidied up indentation, formatting --- OnTopic/Repositories/ITopicRepository.cs | 14 ++++++-------- OnTopic/Repositories/TopicRepositoryDecorator.cs | 6 +++--- OnTopic/Topic.cs | 5 ++--- 3 files changed, 11 insertions(+), 14 deletions(-) diff --git a/OnTopic/Repositories/ITopicRepository.cs b/OnTopic/Repositories/ITopicRepository.cs index 8b4aa259..51878a51 100644 --- a/OnTopic/Repositories/ITopicRepository.cs +++ b/OnTopic/Repositories/ITopicRepository.cs @@ -89,8 +89,7 @@ public interface ITopicRepository { public Task Load() => Load(-1); /// - /// Loads a (and, optionally, all of its descendants) based on the specified . + /// Loads a (and, optionally, all of its descendants) based on the specified . /// /// The topic identifier. /// @@ -111,8 +110,7 @@ public interface ITopicRepository { ); /// - /// Loads a (and, optionally, all of its descendants) based on the specified . + /// Loads a (and, optionally, all of its descendants) based on a specified . /// /// The fully-qualified unique topic key. /// @@ -140,8 +138,8 @@ public interface ITopicRepository { Task Load(string? uniqueKey, bool isRecursive); /// - /// Loads a specific version of a based on its and . + /// Loads a specific version of a based on its and . /// /// /// This overload does not accept an argument for recursion; it will only load a single instance of a version. Further, @@ -179,8 +177,8 @@ public interface ITopicRepository { | METHOD: REFRESH \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Updates the topic graph represented by the by loading any changes the specified . + /// Updates the topic graph represented by the by loading any changes the specified . /// /// /// The method is intended to provide basic synchronization of core attributes, diff --git a/OnTopic/Repositories/TopicRepositoryDecorator.cs b/OnTopic/Repositories/TopicRepositoryDecorator.cs index 88f16aed..f14c0304 100644 --- a/OnTopic/Repositories/TopicRepositoryDecorator.cs +++ b/OnTopic/Repositories/TopicRepositoryDecorator.cs @@ -51,10 +51,10 @@ protected TopicRepositoryDecorator(ITopicRepository topicRepository) { /*-------------------------------------------------------------------------------------------------------------------------- | Subscribe to underlying events \-------------------------------------------------------------------------------------------------------------------------*/ - TopicRepository.TopicLoaded += (_, args) => OnTopicLoaded(args); - TopicRepository.TopicSaved += (_, args) => OnTopicSaved(args); + TopicRepository.TopicLoaded += (_, args) => OnTopicLoaded(args); + TopicRepository.TopicSaved += (_, args) => OnTopicSaved(args); TopicRepository.TopicDeleted += (_, args) => OnTopicDeleted(args); - TopicRepository.TopicMoved += (_, args) => OnTopicMoved(args); + TopicRepository.TopicMoved += (_, args) => OnTopicMoved(args); TopicRepository.TopicRenamed += (_, args) => OnTopicRenamed(args); } diff --git a/OnTopic/Topic.cs b/OnTopic/Topic.cs index b31c09f5..46b5fbfb 100644 --- a/OnTopic/Topic.cs +++ b/OnTopic/Topic.cs @@ -487,7 +487,7 @@ public bool IsDisabled { \---------------------------------------------------------------------------------------------------------------------------*/ /// /// Determines whether or not a topic should be visible based on IsHidden, IsDisabled, and an optional parameter - /// specifying whether or not to show disabled items (which may by triggered if, for example, a user is an administrator). + /// specifying whether or not to show disabled items (which may be triggered if, for example, a user is an administrator). /// /// /// If an item is not marked as IsVisible, then the item will not be visible independent of whether showDisabled is set. @@ -589,7 +589,7 @@ public DateTime LastModified { \---------------------------------------------------------------------------------------------------------------------------*/ /// - KeyedTopicCollection ITopicBackingAccessor.Children => _children; + KeyedTopicCollection ITopicBackingAccessor.Children => _children; /// TopicRelationshipMultiMap ITopicBackingAccessor.Relationships => _relationships; @@ -762,7 +762,6 @@ public bool IsDirty(bool checkCollections, bool excludeLastModified = false) { /// public bool IsDirty(string key) => IsDirty(key, false); - /// public bool IsDirty(string key, bool checkCollections) { if (IsNew || _dirtyKeys.IsDirty(key)) { From 7251476142c9f09c2897d50ae30dbd41cc885348 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 10 Jul 2026 19:05:30 -0700 Subject: [PATCH 141/337] Established new `VersionHistoryCollection` This will provide a backing field for the `Topic.VersionHistory` property. Because it includes `LoadState`, it will be able able to be used as part of the lazy-loading infrastructure (#111). --- .../Collections/VersionHistoryCollection.cs | 32 +++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 OnTopic/Collections/VersionHistoryCollection.cs diff --git a/OnTopic/Collections/VersionHistoryCollection.cs b/OnTopic/Collections/VersionHistoryCollection.cs new file mode 100644 index 00000000..e9c10958 --- /dev/null +++ b/OnTopic/Collections/VersionHistoryCollection.cs @@ -0,0 +1,32 @@ +/*============================================================================================================================== +| Author Ignia, LLC +| Client Ignia, LLC +| Project Topics Library +\=============================================================================================================================*/ +using System.Collections.ObjectModel; + +namespace OnTopic.Collections; + +/*============================================================================================================================== +| CLASS: VERSION HISTORY COLLECTION +\-----------------------------------------------------------------------------------------------------------------------------*/ +/// +/// Provides a collection of values representing past versions of a . +/// +public class VersionHistoryCollection: Collection { + + /*============================================================================================================================ + | PROPERTY: LOAD STATE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Indicates whether the collection has been populated from the underlying , + /// allowing callers to distinguish data that is present and authoritative from data that must still be loaded. + /// + /// + /// Defaults to , reflecting that a newly constructed, in-memory topic has nothing deferred. + /// When a topic is loaded from the persistence store without its version history, the repository sets this to to indicate that it has not yet been loaded. + /// + public LoadState LoadState { get; set; } = LoadState.Loaded; + +} //Class \ No newline at end of file From 609b5aab1e3eeec95a3467abf51f93c386e6185c Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 10 Jul 2026 19:08:24 -0700 Subject: [PATCH 142/337] Use `VersionHistoryCollection` on `VersionHistory` This applies the new `VersionHistoryCollection` (72514761) to the `Topic.VersionHistory` property, and also establishes it as a backing field. This contributes toward #111. --- OnTopic/Topic.cs | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/OnTopic/Topic.cs b/OnTopic/Topic.cs index 46b5fbfb..4ab19737 100644 --- a/OnTopic/Topic.cs +++ b/OnTopic/Topic.cs @@ -3,7 +3,6 @@ | Client Ignia, LLC | Project Topics Library \=============================================================================================================================*/ -using System.Collections.ObjectModel; using System.Globalization; using OnTopic.Associations; using OnTopic.Collections; @@ -32,6 +31,7 @@ public class Topic: ITrackDirtyKeys, ITopicBackingAccessor { private readonly KeyedTopicCollection _children = new(); private readonly TopicRelationshipMultiMap _relationships; private readonly TopicReferenceCollection _references; + private readonly VersionHistoryCollection _versionHistory = new(); readonly DirtyKeyCollection _dirtyKeys = new(); /*============================================================================================================================ @@ -65,7 +65,6 @@ public Topic(string key, string contentType, Topic? parent = null, int id = -1) IncomingRelationships = new(this, true); _relationships = new(this); _references = new(this); - VersionHistory = new(); /*-------------------------------------------------------------------------------------------------------------------------- | Set entity identifier, if present @@ -566,7 +565,7 @@ public string? Description { /// !string.IsNullOrWhiteSpace(value.ToString()) /// public DateTime LastModified { - get => Attributes.GetDateTime("LastModified", VersionHistory.DefaultIfEmpty(DateTime.MinValue).LastOrDefault()); + get => Attributes.GetDateTime("LastModified", _versionHistory.DefaultIfEmpty(DateTime.MinValue).LastOrDefault()); set => SetAttributeValue("LastModified", value.ToString(CultureInfo.InvariantCulture)); } @@ -976,7 +975,11 @@ public TopicReferenceCollection References { /// its derived providers). /// /// The current 's version history. - public Collection VersionHistory { get; } + public VersionHistoryCollection VersionHistory { + get { + return _versionHistory; + } + } #endregion From 10959ed08badacb7688515dd7ac299e4c6f2d9f2 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 10 Jul 2026 19:10:36 -0700 Subject: [PATCH 143/337] Added `VersionHistory` to `ITopicBackingAccessor` This adds the `Topic.VersionHistory` property, which now has a backing field (609b5aab), to the `ITopicBackingAccessor` so that it can be utilized with lazy loading (#111). This also implements that new property on `Topic`. --- OnTopic/Repositories/ITopicBackingAccessor.cs | 12 ++++++++++++ OnTopic/Topic.cs | 3 +++ 2 files changed, 15 insertions(+) diff --git a/OnTopic/Repositories/ITopicBackingAccessor.cs b/OnTopic/Repositories/ITopicBackingAccessor.cs index 96698997..52210119 100644 --- a/OnTopic/Repositories/ITopicBackingAccessor.cs +++ b/OnTopic/Repositories/ITopicBackingAccessor.cs @@ -76,4 +76,16 @@ public interface ITopicBackingAccessor { /// AttributeCollection Attributes { get; } + /*============================================================================================================================ + | PROPERTY: VERSION HISTORY + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Returns the raw backing field, bypassing the autoloading getter. + /// + /// + /// This is to be applied as explicit interface implementations; callers must cast to to + /// access this member. + /// + VersionHistoryCollection VersionHistory { get; } + } //Interface \ No newline at end of file diff --git a/OnTopic/Topic.cs b/OnTopic/Topic.cs index 4ab19737..caa621d9 100644 --- a/OnTopic/Topic.cs +++ b/OnTopic/Topic.cs @@ -599,6 +599,9 @@ public DateTime LastModified { /// AttributeCollection ITopicBackingAccessor.Attributes => Attributes; + /// + VersionHistoryCollection ITopicBackingAccessor.VersionHistory => _versionHistory; + #endregion #region Relationship and Collection Methods From 8fa4a9324107bebcaf00daec0160a9962506a13b Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 10 Jul 2026 19:13:31 -0700 Subject: [PATCH 144/337] Added `VersionHistory` to `TopicPayload` This paves the way for it being sent to either `Load()` or `EnsureLoaded()` as part of the lazy-loading implementation (#111). --- OnTopic/Repositories/TopicPayload.cs | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/OnTopic/Repositories/TopicPayload.cs b/OnTopic/Repositories/TopicPayload.cs index 86cb3bca..a7183ae2 100644 --- a/OnTopic/Repositories/TopicPayload.cs +++ b/OnTopic/Repositories/TopicPayload.cs @@ -14,6 +14,10 @@ namespace OnTopic.Repositories; /// Load() overloads to control how much data is fetched in the first place, and on 's /// Ensure() method to specify which previously deferred data to fill on demand. /// +/// +/// , , , , and +/// all have lazy-loading fill paths via . +/// [Flags] public enum TopicPayload { @@ -59,12 +63,20 @@ public enum TopicPayload { /// References = 1 << 3, + /*---------------------------------------------------------------------------------------------------------------------------- + | VERSION HISTORY + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Version history is included. + /// + VersionHistory = 1 << 4, + /*---------------------------------------------------------------------------------------------------------------------------- | ALL \---------------------------------------------------------------------------------------------------------------------------*/ /// /// All payload data. This ensures a comprehensive loading of all available data. /// - All = Children | ExtendedAttributes | Relationships | References, + All = Children | ExtendedAttributes | Relationships | References | VersionHistory, } //Enum \ No newline at end of file From d9723f0be6ae8561e22eb56a82e07e8c87fb180c Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 10 Jul 2026 19:15:17 -0700 Subject: [PATCH 145/337] `VersionHistory` in `IsLoaded()`, `SetLoadState()` Added the new `TopicPayload.VersionHistory` to the `Topic.IsLoaded()` and `Topic.SetLoadState()` methods so it's supported as part of the lazy-loading state checks (#111). --- OnTopic/Topic.cs | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/OnTopic/Topic.cs b/OnTopic/Topic.cs index caa621d9..d4371a3b 100644 --- a/OnTopic/Topic.cs +++ b/OnTopic/Topic.cs @@ -203,6 +203,11 @@ public bool IsLoaded(TopicPayload payload) { return false; } + // History + if (payload.HasFlag(TopicPayload.VersionHistory) && _versionHistory.LoadState is not LoadState.Loaded) { + return false; + } + // Unexpected return true; @@ -235,6 +240,11 @@ public void SetLoadState(TopicPayload payload, LoadState state) { Attributes.LoadState = state; } + // History + if (payload.HasFlag(TopicPayload.VersionHistory)) { + _versionHistory.LoadState = state; + } + } /*============================================================================================================================ From 155a605761c8ccf71404f2ec7d3308b103bb93a5 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 10 Jul 2026 19:45:20 -0700 Subject: [PATCH 146/337] Set `LoadState` in `SetVersionHistory()` First, in `AddTopic()`, default to `Topic.VersionHistory.LoadState` of `NotLoaded` for all new topics loaded. Then, each time `SetVersionHistory()` is called in response to version history being returned from the `GetTopics` stored procedure, set the `LoadState` to `Loaded`. This properly tracks lazy-loading state of `Topic.History` for the lazy-loading implementation (#111). --- OnTopic.Data.Sql/SqlDataReaderExtensions.cs | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs index 6ea24612..57bd1083 100644 --- a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs +++ b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs @@ -237,6 +237,8 @@ private static Topic AddTopic(this IDataReader reader, TopicIndex topics, bool? if (!topics.TryGetValue(topicId, out var current)) { current = TopicFactory.Create(key, contentType, topicId); topics.Add(current.Id, current); + // Default to NotLoaded; a corresponding row in the version history dataset, if any, promotes this to Loaded + ((ITopicBackingAccessor)current).VersionHistory.LoadState = LoadState.NotLoaded; } else { wasDirty = current.IsDirty(); @@ -614,13 +616,18 @@ private static void SetVersionHistory(this IDataReader reader, TopicIndex topics | Identify topic \-------------------------------------------------------------------------------------------------------------------------*/ var current = topics[topicId]; + var rawTopic = (ITopicBackingAccessor)current; /*-------------------------------------------------------------------------------------------------------------------------- | Set history + >------------------------------------------------------------------------------------------------------------------------- + | A row being present, regardless of its content, means version history was fetched for this topic; promote the state + | to Loaded so subsequent access doesn't trigger a redundant fill. \-------------------------------------------------------------------------------------------------------------------------*/ - if (!current.VersionHistory.Contains(dateTime)) { - current.VersionHistory.Add(dateTime); + if (!rawTopic.VersionHistory.Contains(dateTime)) { + rawTopic.VersionHistory.Add(dateTime); } + rawTopic.VersionHistory.LoadState = LoadState.Loaded; } From b28a31aa345496180b98197d4bb489a69be5b0e0 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 10 Jul 2026 19:54:36 -0700 Subject: [PATCH 147/337] Lazy-load `VersionHistory` in `EnsureLoaded()` MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This exposes the `SetVersionHistory()` method—which was recently updated to support lazy-loading state (155a6057)—to be called from the `EnsureLoaded()` method of `SqlTopicRepository`. This includes adding the `IncludeHistory` parameter to the `GetTopics` stored procedure call, adding the `ReadAsync()` call for the history data set, which had previously just been ignored, adding `VersionHistory` to the gate that allows calls to `EnsureLoaded()` proceeds, and finally making the `IDataReader.SetVersionHistory()` extension method public so it can be called from `EnsureLoaded()`, along with its peers. This contributes to #111. --- OnTopic.Data.Sql/SqlDataReaderExtensions.cs | 2 +- OnTopic.Data.Sql/SqlTopicRepository.cs | 17 ++++++++++++++--- 2 files changed, 15 insertions(+), 4 deletions(-) diff --git a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs index 57bd1083..4ca723bf 100644 --- a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs +++ b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs @@ -604,7 +604,7 @@ internal static void SetReferences(this IDataReader reader, TopicIndex topics, b /// /// The with output from the GetTopics stored procedure. /// A of topics to be loaded. - private static void SetVersionHistory(this IDataReader reader, TopicIndex topics) { + internal static void SetVersionHistory(this IDataReader reader, TopicIndex topics) { /*-------------------------------------------------------------------------------------------------------------------------- | Identify attributes diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index 5f81301a..5415a6c1 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -407,7 +407,11 @@ public virtual async Task EnsureLoaded(Topic topic, TopicPayload payload, Cancel } // Exit early if nothing else is pending so we don't open a database connection unnecessarily - if (!payload.HasFlag(TopicPayload.Children) && !payload.HasFlag(TopicPayload.ExtendedAttributes)) { + if ( + !payload.HasFlag(TopicPayload.Children) && + !payload.HasFlag(TopicPayload.ExtendedAttributes) && + !payload.HasFlag(TopicPayload.VersionHistory) + ) { return; } @@ -478,6 +482,12 @@ public virtual async Task EnsureLoaded(Topic topic, TopicPayload payload, Cancel reader.SetReferences(topics, markDirty: false); } + // History + await reader.NextResultAsync(cancellationToken).ConfigureAwait(false); + while (await reader.ReadAsync(cancellationToken).ConfigureAwait(false)) { + reader.SetVersionHistory(topics); + } + } catch (SqlException exception) { throw new TopicRepositoryException($"Topic payload failed to load: '{exception.Message}'", exception); @@ -499,7 +509,8 @@ public virtual async Task EnsureLoaded(Topic topic, TopicPayload payload, Cancel | Mark confirmed payload as Loaded >--------------------------------------------------------------------------------------------------------------------------- | Children is excluded: Its LoadState is set inside FillChildren() after a successful fill. Relationships and References - | are computed from Deferred.Count and require no explicit assignment here. Only Extended Attributes needs to be set. + | are computed from Deferred.Count and require no explicit assignment here. History is set directly by SetVersionHistory() + | as rows are read, since every persisted topic has at least one version. Only Extended Attributes needs to be set here. \-------------------------------------------------------------------------------------------------------------------------*/ topic.SetLoadState(payload & TopicPayload.ExtendedAttributes, LoadState.Loaded); @@ -828,7 +839,7 @@ private static void AddEnsureLoadedParameters(SqlCommand command, int topicId, T command.AddParameter("IncludeExtended", payload.HasFlag(TopicPayload.ExtendedAttributes)); command.AddParameter("IncludeRelationships", payload.HasFlag(TopicPayload.Children)); command.AddParameter("IncludeReferences", payload.HasFlag(TopicPayload.Children)); - command.AddParameter("IncludeHistory", false); + command.AddParameter("IncludeHistory", payload.HasFlag(TopicPayload.VersionHistory)); } From dea4bc932103683efe5271a252a497ef365d250d Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 10 Jul 2026 19:58:30 -0700 Subject: [PATCH 148/337] Lazy-load `VersionHistory` in `Load()` Since version history was already handled in `Load()`, this just entails conditionally setting the `IncludeHistory` parameter to the `GetTopics` stored procedure (8c2c81da). This satisfied the requirements for lazy-loading (#111) `History` in `SqlTopicRepository`. --- OnTopic.Data.Sql/SqlTopicRepository.cs | 1 + 1 file changed, 1 insertion(+) diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index 5415a6c1..7a87f2a5 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -145,6 +145,7 @@ public SqlTopicRepository(string connectionString) { command.AddParameter("IncludeExtended", payload.HasFlag(TopicPayload.ExtendedAttributes)); command.AddParameter("IncludeRelationships", true); command.AddParameter("IncludeReferences", true); + command.AddParameter("IncludeHistory", payload.HasFlag(TopicPayload.VersionHistory)); /*-------------------------------------------------------------------------------------------------------------------------- | Process database query From 09f4d0b573d4ee7fb7aae33697aadcb942869dcd Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 10 Jul 2026 20:00:35 -0700 Subject: [PATCH 149/337] Wire-up dynamic loading of `VersionHistory` The completes the implementation of supporting lazy-loading (#111) of the `Topic.VersionHistory` property. This is supported by prior commits: 10959ed0, 8fa4a932, d9723f0b, 155a6057, b28a31aa, dea4bc93. --- OnTopic/Topic.cs | 3 +++ 1 file changed, 3 insertions(+) diff --git a/OnTopic/Topic.cs b/OnTopic/Topic.cs index d4371a3b..5489dfdf 100644 --- a/OnTopic/Topic.cs +++ b/OnTopic/Topic.cs @@ -990,6 +990,9 @@ public TopicReferenceCollection References { /// The current 's version history. public VersionHistoryCollection VersionHistory { get { + if (_versionHistory.LoadState is LoadState.NotLoaded) { + EnsureLoaded(TopicPayload.VersionHistory).GetAwaiter().GetResult(); + } return _versionHistory; } } From d70f75129f8e0f4a8e27a88cc62d1eac86c76a92 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 10 Jul 2026 20:01:41 -0700 Subject: [PATCH 150/337] Reviewed and tidied up XML docblock remarks --- OnTopic.Data.Sql/SqlTopicRepository.cs | 10 ++++------ OnTopic.Tests/TopicRepositoryBaseTest.cs | 14 ++++++++------ OnTopic/Repositories/ITopicRepository.cs | 14 ++++++++++---- 3 files changed, 22 insertions(+), 16 deletions(-) diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index 7a87f2a5..7cd612cb 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -498,7 +498,7 @@ public virtual async Task EnsureLoaded(Topic topic, TopicPayload payload, Cancel | Raise event for each newly loaded child >--------------------------------------------------------------------------------------------------------------------------- | Children filled here, as opposed to the initial recursive Load(), are new Topic instances introduced to the graph for the - | first time—conceptually the same as being loaded via Load(), just via a different entry point. + | first time and are conceptually the same as being loaded via Load(), just via a different entry point. \-------------------------------------------------------------------------------------------------------------------------*/ if (payload.HasFlag(TopicPayload.Children)) { foreach (var child in topic.Children) { @@ -818,11 +818,9 @@ protected override sealed async Task DeleteTopic(Topic topic) { /// setting the payload parameters based on the requested . /// /// - /// Scope is always None (i.e., a single node) for resolver fills, as the caller is already in the graph. is hardcoded to false here because its fill path is not yet implemented; once - /// it is, this method will map it from the flag. Indexed attributes and associations are only - /// requested when filling the boundary, as they are otherwise always loaded as part of - /// the initial for existing topics. + /// Indexed attributes and associations are only requested when filling the boundary, + /// as they are otherwise always loaded as part of the initial for + /// existing topics. /// private static void AddEnsureLoadedParameters(SqlCommand command, int topicId, TopicPayload payload) { diff --git a/OnTopic.Tests/TopicRepositoryBaseTest.cs b/OnTopic.Tests/TopicRepositoryBaseTest.cs index b9a6b2cb..cc5e6942 100644 --- a/OnTopic.Tests/TopicRepositoryBaseTest.cs +++ b/OnTopic.Tests/TopicRepositoryBaseTest.cs @@ -1227,9 +1227,10 @@ public async Task EnsureLoaded_MixedBoundaries_SkipsLoadedBoundaries() { /// /> via the 's fill. /// /// - /// On-demand fetching of non-resident relationship targets is deferred to lazy-loading-plan.md Task 6. A stub fill - /// simply marks the boundary ; the SQL resolver leaves it - /// whenever any target is not resident in the single-node topic index it currently uses. + /// On-demand fetching of non-resident relationship targets happens via ResolveDeferredAssociations() on , which only invokes from its own + /// EnsureLoaded()— does not resolve deferred targets itself. This test's stub fill + /// simply marks the boundary without resolving the deferred target. /// [Fact] public async Task EnsureLoaded_RelationshipsNotLoaded_MarksLoaded() { @@ -1252,9 +1253,10 @@ public async Task EnsureLoaded_RelationshipsNotLoaded_MarksLoaded() { /// via the 's fill. /// /// - /// On-demand fetching of non-resident reference targets is deferred to lazy-loading-plan.md Task 6. A stub fill - /// simply marks the boundary ; the SQL resolver leaves it - /// whenever any target is not resident in the single-node topic index it currently uses. + /// On-demand fetching of non-resident reference targets happens via ResolveDeferredAssociations() on , which only invokes from its own + /// EnsureLoaded()— does not resolve deferred targets itself. This test's stub fill + /// simply marks the boundary without resolving the deferred target. /// [Fact] public async Task EnsureLoaded_ReferencesNotLoaded_MarksLoaded() { diff --git a/OnTopic/Repositories/ITopicRepository.cs b/OnTopic/Repositories/ITopicRepository.cs index 51878a51..5f8b1a44 100644 --- a/OnTopic/Repositories/ITopicRepository.cs +++ b/OnTopic/Repositories/ITopicRepository.cs @@ -24,10 +24,16 @@ public interface ITopicRepository { /// "ITopicRepository.Load(String, Topic?, Boolean, TopicPayload)"/> operation, or one of its overloads. /// /// - /// The event should only be raised when a new is loaded from the underlying - /// persistence store. It should not be loaded, for example, if a value is loaded from the cache, or a topicId is - /// queried from the database. Given this, this event will need to be raised in actual implementations, since it is - /// specific to the business logic of each . + /// + /// The event should only be raised when a new is loaded from the underlying + /// persistence store—not, for example, when a value is returned from a cache, or a topicId is merely queried from + /// the database. + /// + /// + /// Raising this reliably is more than a courtesy. As a concrete example, the lazy-loading resolver stamping is driven by + /// this event, so an that fails to raise it will leave loaded topics unable to lazy load + /// their own deferred payload. + /// /// event EventHandler TopicLoaded; From ec9f740e00ffca3fbf96f197992847c4d7643dec Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 10 Jul 2026 20:10:10 -0700 Subject: [PATCH 151/337] Name `LoadTopicGraphAsync()` as `LoadTopicGraph()` Oops! When I made `LoadTopicGraph()` async (a3b73602) I accidentally "kept" the `Async` suffix, making it `LoadTopicGraphAsync()`. That's because, originally, the plan had been to keep the synchronous version, but I ended up rethinking that before committing. This renames it back to `LoadTopicGraph()` --- OnTopic.Data.Sql/SqlDataReaderExtensions.cs | 2 +- OnTopic.Data.Sql/SqlTopicRepository.cs | 6 +-- OnTopic.Tests/SqlTopicRepositoryTest.cs | 48 ++++++++++----------- 3 files changed, 28 insertions(+), 28 deletions(-) diff --git a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs index 4ca723bf..ae087dd4 100644 --- a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs +++ b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs @@ -60,7 +60,7 @@ internal static class SqlDataReaderExtensions { /*============================================================================================================================ | METHOD: LOAD TOPIC GRAPH \---------------------------------------------------------------------------------------------------------------------------*/ - internal static async Task LoadTopicGraphAsync( + internal static async Task LoadTopicGraph( this DbDataReader reader, int seedTopicId = -1, Topic? referenceTopic = null, diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index 7cd612cb..26ebae29 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -153,7 +153,7 @@ public SqlTopicRepository(string connectionString) { try { await connection.OpenAsync().ConfigureAwait(false); using var reader = (SqlDataReader)await command.ExecuteReaderAsync().ConfigureAwait(false); - topic = await reader.LoadTopicGraphAsync(topicId, referenceTopic, false).ConfigureAwait(false); + topic = await reader.LoadTopicGraph(topicId, referenceTopic, false).ConfigureAwait(false); } /*-------------------------------------------------------------------------------------------------------------------------- @@ -266,7 +266,7 @@ public SqlTopicRepository(string connectionString) { } // Load the historical version into the current topic graph - topic = await reader.LoadTopicGraphAsync( + topic = await reader.LoadTopicGraph( topicId, referenceTopic, includeExternalReferences: referenceTopic is not null @@ -357,7 +357,7 @@ public override async Task Refresh(Topic referenceTopic, DateTime since) { try { await connection.OpenAsync().ConfigureAwait(false); using var reader = (SqlDataReader)await command.ExecuteReaderAsync().ConfigureAwait(false); - await reader.LoadTopicGraphAsync(-1, referenceTopic.GetRootTopic(), false).ConfigureAwait(false); + await reader.LoadTopicGraph(-1, referenceTopic.GetRootTopic(), false).ConfigureAwait(false); } /*-------------------------------------------------------------------------------------------------------------------------- diff --git a/OnTopic.Tests/SqlTopicRepositoryTest.cs b/OnTopic.Tests/SqlTopicRepositoryTest.cs index 1ef2018b..801c9c95 100644 --- a/OnTopic.Tests/SqlTopicRepositoryTest.cs +++ b/OnTopic.Tests/SqlTopicRepositoryTest.cs @@ -41,7 +41,7 @@ public async Task LoadTopicGraph_WithTopic_ReturnsTopic() { using var tableReader = new DataTableReader(topics); - var topic = await tableReader.LoadTopicGraphAsync(); + var topic = await tableReader.LoadTopicGraph(); Assert.NotNull(topic); Assert.Equal(1, topic.Id); @@ -69,7 +69,7 @@ public async Task LoadTopicGraph_WithNewParent_UpdatesParent() { using var tableReader = new DataTableReader(topics); - await tableReader.LoadTopicGraphAsync(referenceTopic: topic); + await tableReader.LoadTopicGraph(referenceTopic: topic); Assert.Equal(parent2, child.Parent); @@ -93,7 +93,7 @@ public async Task LoadTopicGraph_WithAttributes_ReturnsAttributes() { using var tableReader = new DataTableReader([topics, attributes]); - var topic = await tableReader.LoadTopicGraphAsync(); + var topic = await tableReader.LoadTopicGraph(); Assert.NotNull(topic); Assert.Equal(1, topic.Id); @@ -123,7 +123,7 @@ public async Task LoadTopicGraph_WithNullAttributes_RemovesAttribute() { using var tableReader = new DataTableReader([topics, attributes]); - await tableReader.LoadTopicGraphAsync(referenceTopic: topic); + await tableReader.LoadTopicGraph(referenceTopic: topic); Assert.Null(topic.Attributes.GetValue("Test")); @@ -149,7 +149,7 @@ public async Task LoadTopicGraph_WithRelationship_ReturnsRelationship() { using var tableReader = new DataTableReader([topics, empty, empty, relationships]); - var topic = await tableReader.LoadTopicGraphAsync(); + var topic = await tableReader.LoadTopicGraph(); Assert.NotNull(topic); Assert.Equal(1, topic.Id); @@ -177,7 +177,7 @@ public async Task LoadTopicGraph_WithMissingRelationship_NotFullyLoaded() { using var tableReader = new DataTableReader([topics, empty, empty, relationships]); - var topic = await tableReader.LoadTopicGraphAsync(); + var topic = await tableReader.LoadTopicGraph(); Assert.NotNull(topic); Assert.Equal(1, topic.Id); @@ -206,7 +206,7 @@ public async Task LoadTopicGraph_WithReference_ReturnsReference() { using var tableReader = new DataTableReader([topics, empty, empty, empty, references]); - var topic = await tableReader.LoadTopicGraphAsync(); + var topic = await tableReader.LoadTopicGraph(); Assert.NotNull(topic); Assert.Equal(1, topic.Id); @@ -236,7 +236,7 @@ public async Task LoadTopicGraph_WithExternalReference_ReturnsReference() { using var tableReader = new DataTableReader([topics, empty, empty, empty, references]); - var topic = await tableReader.LoadTopicGraphAsync(1, referenceTopic, false); + var topic = await tableReader.LoadTopicGraph(1, referenceTopic, false); Assert.NotNull(topic); Assert.Equal(1, topic.Id); @@ -270,7 +270,7 @@ public async Task LoadTopicGraph_WithDeletedReference_RemovesExistingReference() using var tableReader = new DataTableReader([topics, empty, empty, empty, references]); - await tableReader.LoadTopicGraphAsync(1, referenceTopic, false); + await tableReader.LoadTopicGraph(1, referenceTopic, false); Assert.Null(referenceTopic.References.GetValue("Reference")); Assert.Equal(LoadState.Loaded, referenceTopic.References.LoadState); @@ -296,7 +296,7 @@ public async Task LoadTopicGraph_WithMissingReference_NotFullyLoaded() { using var tableReader = new DataTableReader([topics, empty, empty, empty, references]); - var topic = await tableReader.LoadTopicGraphAsync(); + var topic = await tableReader.LoadTopicGraph(); Assert.NotNull(topic); Assert.Equal(1, topic.Id); @@ -328,7 +328,7 @@ public async Task LoadTopicGraph_WithDeletedRelationship_RemovesRelationship() { using var tableReader = new DataTableReader([empty, empty, empty, relationships]); - await tableReader.LoadTopicGraphAsync(referenceTopic: related); + await tableReader.LoadTopicGraph(referenceTopic: related); Assert.Empty(topic.Relationships.GetValues("Test")); @@ -359,7 +359,7 @@ public async Task LoadTopicGraph_IndexedOnlyWithRelationship_ReturnsLoaded() { using var tableReader = new DataTableReader([topics, empty, empty, relationships]); - var topic = await tableReader.LoadTopicGraphAsync(); + var topic = await tableReader.LoadTopicGraph(); Assert.NotNull(topic); Assert.True(topic.IsLoaded(TopicPayload.Relationships)); @@ -390,7 +390,7 @@ public async Task LoadTopicGraph_IndexedOnlyWithMissingRelationship_ReturnsNotLo using var tableReader = new DataTableReader([topics, empty, empty, relationships]); - var topic = await tableReader.LoadTopicGraphAsync(); + var topic = await tableReader.LoadTopicGraph(); Assert.NotNull(topic); Assert.False(topic.IsLoaded(TopicPayload.Relationships)); @@ -417,7 +417,7 @@ public async Task LoadTopicGraph_IndexedOnlyWithReference_ReturnsLoaded() { using var tableReader = new DataTableReader([topics, empty, empty, empty, references]); - var topic = await tableReader.LoadTopicGraphAsync(); + var topic = await tableReader.LoadTopicGraph(); Assert.NotNull(topic); Assert.True(topic.IsLoaded(TopicPayload.References)); @@ -444,7 +444,7 @@ public async Task LoadTopicGraph_IndexedOnlyWithMissingReference_ReturnsNotLoade using var tableReader = new DataTableReader([topics, empty, empty, empty, references]); - var topic = await tableReader.LoadTopicGraphAsync(); + var topic = await tableReader.LoadTopicGraph(); Assert.NotNull(topic); Assert.False(topic.IsLoaded(TopicPayload.References)); @@ -471,7 +471,7 @@ public async Task LoadTopicGraph_WithMissingRelationship_SetsNotLoaded() { using var tableReader = new DataTableReader([topics, empty, empty, relationships]); - var topic = await tableReader.LoadTopicGraphAsync(); + var topic = await tableReader.LoadTopicGraph(); Assert.NotNull(topic); Assert.False(topic.IsLoaded(TopicPayload.Relationships)); @@ -498,7 +498,7 @@ public async Task LoadTopicGraph_WithMissingReference_SetsNotLoaded() { using var tableReader = new DataTableReader([topics, empty, empty, empty, references]); - var topic = await tableReader.LoadTopicGraphAsync(); + var topic = await tableReader.LoadTopicGraph(); Assert.NotNull(topic); Assert.False(topic.IsLoaded(TopicPayload.References)); @@ -524,7 +524,7 @@ public async Task LoadTopicGraph_WithVersionHistory_ReturnsVersions() { using var tableReader = new DataTableReader([topics, empty, empty, empty, empty, versions]); - var topic = await tableReader.LoadTopicGraphAsync(); + var topic = await tableReader.LoadTopicGraph(); Assert.NotNull(topic); Assert.Equal(1, topic.Id); @@ -550,7 +550,7 @@ public async Task LoadTopicGraph_WithExtendedDeferredAndBlob_ReturnsNotLoaded() using var tableReader = new DataTableReader(topics); - var topic = await tableReader.LoadTopicGraphAsync(); + var topic = await tableReader.LoadTopicGraph(); Assert.NotNull(topic); Assert.False(topic.IsLoaded(TopicPayload.ExtendedAttributes)); @@ -574,7 +574,7 @@ public async Task LoadTopicGraph_WithExtendedDeferredAndNoBlob_ReturnsLoaded() { using var tableReader = new DataTableReader(topics); - var topic = await tableReader.LoadTopicGraphAsync(); + var topic = await tableReader.LoadTopicGraph(); Assert.NotNull(topic); Assert.Equal(LoadState.Loaded, topic.Attributes.LoadState); @@ -598,7 +598,7 @@ public async Task LoadTopicGraph_WithExtendedIncludedAndBlob_ReturnsLoaded() { using var tableReader = new DataTableReader(topics); - var topic = await tableReader.LoadTopicGraphAsync(); + var topic = await tableReader.LoadTopicGraph(); Assert.NotNull(topic); Assert.Equal(LoadState.Loaded, topic.Attributes.LoadState); @@ -622,7 +622,7 @@ public async Task LoadTopicGraph_WithHasChildrenFalse_ReturnsChildrenLoaded() { using var tableReader = new DataTableReader(topics); - var topic = await tableReader.LoadTopicGraphAsync(1); + var topic = await tableReader.LoadTopicGraph(1); Assert.True(topic?.IsLoaded(TopicPayload.Children)); @@ -646,7 +646,7 @@ public async Task LoadTopicGraph_WithHasChildrenAndLoadedChildren_ReturnsChildre using var tableReader = new DataTableReader(topics); - var topic = await tableReader.LoadTopicGraphAsync(1); + var topic = await tableReader.LoadTopicGraph(1); Assert.True(topic?.IsLoaded(TopicPayload.Children)); @@ -674,7 +674,7 @@ public async Task LoadTopicGraph_WithHasChildrenOnAncestorAndLoadedSubtree_SetsL // The seed topic is Child (2); Root (1) is on the ancestor chain and is NotLoaded. // The Child (seed) and Grandchild are in the fully loaded subtree and are Loaded. - var seedTopic = await tableReader.LoadTopicGraphAsync(2); + var seedTopic = await tableReader.LoadTopicGraph(2); var rootTopic = seedTopic?.Parent; Assert.Equal(LoadState.NotLoaded, rootTopic?.Children.LoadState); From f4a3e53573143a86ce44de6e46476a3611a14b9c Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 10 Jul 2026 20:13:34 -0700 Subject: [PATCH 152/337] Merged `FillChildrenAsync()` into `FillChildren()` We are no longer using the original synchronous `FillChildren()` method, so we can replace it with the `FillChildrenAsync()` method (f7fc2669). --- OnTopic.Data.Sql/SqlDataReaderExtensions.cs | 15 +-------------- OnTopic.Data.Sql/SqlTopicRepository.cs | 2 +- 2 files changed, 2 insertions(+), 15 deletions(-) diff --git a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs index ae087dd4..e7b68437 100644 --- a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs +++ b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs @@ -280,20 +280,7 @@ private static Topic AddTopic(this IDataReader reader, TopicIndex topics, bool? /// /// The topic whose immediate children are being loaded. /// The to populate with the new child topics. - internal static void FillChildren(this IDataReader reader, Topic parent, TopicIndex topics) { - - // Loop through each record, delegating to the shared AddChildTopic() - while (reader.Read()) { - reader.AddChildTopic(parent, topics); - } - - // Mark confirmed children payload as Loaded - parent.SetLoadState(TopicPayload.Children, LoadState.Loaded); - - } - - /// - internal static async Task FillChildrenAsync( + internal static async Task FillChildren( this DbDataReader reader, Topic parent, TopicIndex topics, diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index 26ebae29..c440a753 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -445,7 +445,7 @@ public virtual async Task EnsureLoaded(Topic topic, TopicPayload payload, Cancel // Children: Fill first result set; FillChildrenAsync() sets each child's Children.LoadState and marks the parent Loaded if (payload.HasFlag(TopicPayload.Children)) { - await reader.FillChildrenAsync(topic, topics, cancellationToken).ConfigureAwait(false); + await reader.FillChildren(topic, topics, cancellationToken).ConfigureAwait(false); } // Otherwise, skip the first result set since the topic is already resident From c5c12670e1203f9b93cd584039d45f1f94abbe78 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 10 Jul 2026 20:29:55 -0700 Subject: [PATCH 153/337] Added test for deferred `VersionHistory` state This ensures that the `Topic.VersionHistory.LoadState` is `NotLoaded` if no `VersionHistory` was loaded for the `Topic`. This contributes to testing of the lazy-loading infrastructure (#111). --- OnTopic.Tests/SqlTopicRepositoryTest.cs | 32 +++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/OnTopic.Tests/SqlTopicRepositoryTest.cs b/OnTopic.Tests/SqlTopicRepositoryTest.cs index 801c9c95..29c6947f 100644 --- a/OnTopic.Tests/SqlTopicRepositoryTest.cs +++ b/OnTopic.Tests/SqlTopicRepositoryTest.cs @@ -25,6 +25,14 @@ namespace OnTopic.Tests; [ExcludeFromCodeCoverage] public class SqlTopicRepositoryTest { + /*============================================================================================================================ + | PROPERTY: CANCELLATION TOKEN + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Shorthand for 's . + /// + private static CancellationToken CancellationToken => TestContext.Current.CancellationToken; + /*============================================================================================================================ | TEST: LOAD TOPIC GRAPH: WITH TOPIC: RETURNS TOPIC \---------------------------------------------------------------------------------------------------------------------------*/ @@ -505,6 +513,30 @@ public async Task LoadTopicGraph_WithMissingReference_SetsNotLoaded() { } + /*============================================================================================================================ + | TEST: LOAD TOPIC GRAPH: WITH HISTORY DEFERRED: RETURNS NOT LOADED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Calls with no records, as + /// would happen when @IncludeHistory is 0, and confirms the history boundary is , since every persisted topic is expected to have at least one version. + /// + [Fact] + public async Task LoadTopicGraph_WithHistoryDeferred_ReturnsNotLoaded() { + + using var topics = new TopicsDataTable(); + + topics.AddRow(1, "Root", "Container"); + + using var tableReader = new DataTableReader(topics); + + var topic = await tableReader.LoadTopicGraph(cancellationToken: CancellationToken); + + Assert.NotNull(topic); + Assert.False(topic.IsLoaded(TopicPayload.VersionHistory)); + + } + /*============================================================================================================================ | TEST: LOAD TOPIC GRAPH: WITH VERSION HISTORY: RETURNS VERSIONS \---------------------------------------------------------------------------------------------------------------------------*/ From ba648d7764c6a5d61caac844e6a0134d6938eae2 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 10 Jul 2026 20:31:27 -0700 Subject: [PATCH 154/337] Added `CancellationToken` to all async test calls This is supported by the `CancellationToken` I added in the prior commit (c5c12670) to support a new test. --- OnTopic.Tests/SqlTopicRepositoryTest.cs | 48 ++++++++++++------------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/OnTopic.Tests/SqlTopicRepositoryTest.cs b/OnTopic.Tests/SqlTopicRepositoryTest.cs index 29c6947f..31fc84a5 100644 --- a/OnTopic.Tests/SqlTopicRepositoryTest.cs +++ b/OnTopic.Tests/SqlTopicRepositoryTest.cs @@ -49,7 +49,7 @@ public async Task LoadTopicGraph_WithTopic_ReturnsTopic() { using var tableReader = new DataTableReader(topics); - var topic = await tableReader.LoadTopicGraph(); + var topic = await tableReader.LoadTopicGraph(cancellationToken: CancellationToken); Assert.NotNull(topic); Assert.Equal(1, topic.Id); @@ -77,7 +77,7 @@ public async Task LoadTopicGraph_WithNewParent_UpdatesParent() { using var tableReader = new DataTableReader(topics); - await tableReader.LoadTopicGraph(referenceTopic: topic); + await tableReader.LoadTopicGraph(referenceTopic: topic, cancellationToken: CancellationToken); Assert.Equal(parent2, child.Parent); @@ -101,7 +101,7 @@ public async Task LoadTopicGraph_WithAttributes_ReturnsAttributes() { using var tableReader = new DataTableReader([topics, attributes]); - var topic = await tableReader.LoadTopicGraph(); + var topic = await tableReader.LoadTopicGraph(cancellationToken: CancellationToken); Assert.NotNull(topic); Assert.Equal(1, topic.Id); @@ -131,7 +131,7 @@ public async Task LoadTopicGraph_WithNullAttributes_RemovesAttribute() { using var tableReader = new DataTableReader([topics, attributes]); - await tableReader.LoadTopicGraph(referenceTopic: topic); + await tableReader.LoadTopicGraph(referenceTopic: topic, cancellationToken: CancellationToken); Assert.Null(topic.Attributes.GetValue("Test")); @@ -157,7 +157,7 @@ public async Task LoadTopicGraph_WithRelationship_ReturnsRelationship() { using var tableReader = new DataTableReader([topics, empty, empty, relationships]); - var topic = await tableReader.LoadTopicGraph(); + var topic = await tableReader.LoadTopicGraph(cancellationToken: CancellationToken); Assert.NotNull(topic); Assert.Equal(1, topic.Id); @@ -185,7 +185,7 @@ public async Task LoadTopicGraph_WithMissingRelationship_NotFullyLoaded() { using var tableReader = new DataTableReader([topics, empty, empty, relationships]); - var topic = await tableReader.LoadTopicGraph(); + var topic = await tableReader.LoadTopicGraph(cancellationToken: CancellationToken); Assert.NotNull(topic); Assert.Equal(1, topic.Id); @@ -214,7 +214,7 @@ public async Task LoadTopicGraph_WithReference_ReturnsReference() { using var tableReader = new DataTableReader([topics, empty, empty, empty, references]); - var topic = await tableReader.LoadTopicGraph(); + var topic = await tableReader.LoadTopicGraph(cancellationToken: CancellationToken); Assert.NotNull(topic); Assert.Equal(1, topic.Id); @@ -244,7 +244,7 @@ public async Task LoadTopicGraph_WithExternalReference_ReturnsReference() { using var tableReader = new DataTableReader([topics, empty, empty, empty, references]); - var topic = await tableReader.LoadTopicGraph(1, referenceTopic, false); + var topic = await tableReader.LoadTopicGraph(1, referenceTopic, false, cancellationToken: CancellationToken); Assert.NotNull(topic); Assert.Equal(1, topic.Id); @@ -278,7 +278,7 @@ public async Task LoadTopicGraph_WithDeletedReference_RemovesExistingReference() using var tableReader = new DataTableReader([topics, empty, empty, empty, references]); - await tableReader.LoadTopicGraph(1, referenceTopic, false); + await tableReader.LoadTopicGraph(1, referenceTopic, false, cancellationToken: CancellationToken); Assert.Null(referenceTopic.References.GetValue("Reference")); Assert.Equal(LoadState.Loaded, referenceTopic.References.LoadState); @@ -304,7 +304,7 @@ public async Task LoadTopicGraph_WithMissingReference_NotFullyLoaded() { using var tableReader = new DataTableReader([topics, empty, empty, empty, references]); - var topic = await tableReader.LoadTopicGraph(); + var topic = await tableReader.LoadTopicGraph(cancellationToken: CancellationToken); Assert.NotNull(topic); Assert.Equal(1, topic.Id); @@ -336,7 +336,7 @@ public async Task LoadTopicGraph_WithDeletedRelationship_RemovesRelationship() { using var tableReader = new DataTableReader([empty, empty, empty, relationships]); - await tableReader.LoadTopicGraph(referenceTopic: related); + await tableReader.LoadTopicGraph(referenceTopic: related, cancellationToken: CancellationToken); Assert.Empty(topic.Relationships.GetValues("Test")); @@ -367,7 +367,7 @@ public async Task LoadTopicGraph_IndexedOnlyWithRelationship_ReturnsLoaded() { using var tableReader = new DataTableReader([topics, empty, empty, relationships]); - var topic = await tableReader.LoadTopicGraph(); + var topic = await tableReader.LoadTopicGraph(cancellationToken: CancellationToken); Assert.NotNull(topic); Assert.True(topic.IsLoaded(TopicPayload.Relationships)); @@ -398,7 +398,7 @@ public async Task LoadTopicGraph_IndexedOnlyWithMissingRelationship_ReturnsNotLo using var tableReader = new DataTableReader([topics, empty, empty, relationships]); - var topic = await tableReader.LoadTopicGraph(); + var topic = await tableReader.LoadTopicGraph(cancellationToken: CancellationToken); Assert.NotNull(topic); Assert.False(topic.IsLoaded(TopicPayload.Relationships)); @@ -425,7 +425,7 @@ public async Task LoadTopicGraph_IndexedOnlyWithReference_ReturnsLoaded() { using var tableReader = new DataTableReader([topics, empty, empty, empty, references]); - var topic = await tableReader.LoadTopicGraph(); + var topic = await tableReader.LoadTopicGraph(cancellationToken: CancellationToken); Assert.NotNull(topic); Assert.True(topic.IsLoaded(TopicPayload.References)); @@ -452,7 +452,7 @@ public async Task LoadTopicGraph_IndexedOnlyWithMissingReference_ReturnsNotLoade using var tableReader = new DataTableReader([topics, empty, empty, empty, references]); - var topic = await tableReader.LoadTopicGraph(); + var topic = await tableReader.LoadTopicGraph(cancellationToken: CancellationToken); Assert.NotNull(topic); Assert.False(topic.IsLoaded(TopicPayload.References)); @@ -479,7 +479,7 @@ public async Task LoadTopicGraph_WithMissingRelationship_SetsNotLoaded() { using var tableReader = new DataTableReader([topics, empty, empty, relationships]); - var topic = await tableReader.LoadTopicGraph(); + var topic = await tableReader.LoadTopicGraph(cancellationToken: CancellationToken); Assert.NotNull(topic); Assert.False(topic.IsLoaded(TopicPayload.Relationships)); @@ -506,7 +506,7 @@ public async Task LoadTopicGraph_WithMissingReference_SetsNotLoaded() { using var tableReader = new DataTableReader([topics, empty, empty, empty, references]); - var topic = await tableReader.LoadTopicGraph(); + var topic = await tableReader.LoadTopicGraph(cancellationToken: CancellationToken); Assert.NotNull(topic); Assert.False(topic.IsLoaded(TopicPayload.References)); @@ -556,7 +556,7 @@ public async Task LoadTopicGraph_WithVersionHistory_ReturnsVersions() { using var tableReader = new DataTableReader([topics, empty, empty, empty, empty, versions]); - var topic = await tableReader.LoadTopicGraph(); + var topic = await tableReader.LoadTopicGraph(cancellationToken: CancellationToken); Assert.NotNull(topic); Assert.Equal(1, topic.Id); @@ -582,7 +582,7 @@ public async Task LoadTopicGraph_WithExtendedDeferredAndBlob_ReturnsNotLoaded() using var tableReader = new DataTableReader(topics); - var topic = await tableReader.LoadTopicGraph(); + var topic = await tableReader.LoadTopicGraph(cancellationToken: CancellationToken); Assert.NotNull(topic); Assert.False(topic.IsLoaded(TopicPayload.ExtendedAttributes)); @@ -606,7 +606,7 @@ public async Task LoadTopicGraph_WithExtendedDeferredAndNoBlob_ReturnsLoaded() { using var tableReader = new DataTableReader(topics); - var topic = await tableReader.LoadTopicGraph(); + var topic = await tableReader.LoadTopicGraph(cancellationToken: CancellationToken); Assert.NotNull(topic); Assert.Equal(LoadState.Loaded, topic.Attributes.LoadState); @@ -630,7 +630,7 @@ public async Task LoadTopicGraph_WithExtendedIncludedAndBlob_ReturnsLoaded() { using var tableReader = new DataTableReader(topics); - var topic = await tableReader.LoadTopicGraph(); + var topic = await tableReader.LoadTopicGraph(cancellationToken: CancellationToken); Assert.NotNull(topic); Assert.Equal(LoadState.Loaded, topic.Attributes.LoadState); @@ -654,7 +654,7 @@ public async Task LoadTopicGraph_WithHasChildrenFalse_ReturnsChildrenLoaded() { using var tableReader = new DataTableReader(topics); - var topic = await tableReader.LoadTopicGraph(1); + var topic = await tableReader.LoadTopicGraph(1, cancellationToken: CancellationToken); Assert.True(topic?.IsLoaded(TopicPayload.Children)); @@ -678,7 +678,7 @@ public async Task LoadTopicGraph_WithHasChildrenAndLoadedChildren_ReturnsChildre using var tableReader = new DataTableReader(topics); - var topic = await tableReader.LoadTopicGraph(1); + var topic = await tableReader.LoadTopicGraph(1, cancellationToken: CancellationToken); Assert.True(topic?.IsLoaded(TopicPayload.Children)); @@ -706,7 +706,7 @@ public async Task LoadTopicGraph_WithHasChildrenOnAncestorAndLoadedSubtree_SetsL // The seed topic is Child (2); Root (1) is on the ancestor chain and is NotLoaded. // The Child (seed) and Grandchild are in the fully loaded subtree and are Loaded. - var seedTopic = await tableReader.LoadTopicGraph(2); + var seedTopic = await tableReader.LoadTopicGraph(2, cancellationToken: CancellationToken); var rootTopic = seedTopic?.Parent; Assert.Equal(LoadState.NotLoaded, rootTopic?.Children.LoadState); From cf92ed3b81f368d62dc5b3102aa1eb57f327a1f5 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 10 Jul 2026 21:18:36 -0700 Subject: [PATCH 155/337] Default `Load()` to a sparse, lazy-loaded graph Historically, the default with `Load()` was to eagerly load the entirety of the tree, top-to-bottom. With the introduction of lazy loading (#111), however, I'm flipping this so that, by default, a sparsely populated "graph" is populated, which just contains the root topic, and then everything else is eagerly loaded. This is a pretty big shift, but fulfills the promise of lazy loading. --- .../Repositories/StubTopicRepository.cs | 8 ++++---- .../TestDoubles/TestTopicRepository.cs | 4 ++-- OnTopic.Data.Caching/CachedTopicRepository.cs | 8 ++++---- OnTopic.Data.Sql/SqlTopicRepository.cs | 8 ++++---- OnTopic.TestDoubles/DummyTopicRepository.cs | 8 ++++---- OnTopic.TestDoubles/StubTopicRepository.cs | 8 ++++---- OnTopic/Repositories/ITopicRepository.cs | 11 ++++++----- OnTopic/Repositories/ObservableTopicRepository.cs | 8 ++++---- OnTopic/Repositories/TopicPayload.cs | 6 ++++++ OnTopic/Repositories/TopicRepositoryDecorator.cs | 8 ++++---- 10 files changed, 42 insertions(+), 35 deletions(-) diff --git a/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/Repositories/StubTopicRepository.cs b/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/Repositories/StubTopicRepository.cs index 31cc6efd..27172960 100644 --- a/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/Repositories/StubTopicRepository.cs +++ b/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/Repositories/StubTopicRepository.cs @@ -45,8 +45,8 @@ public StubTopicRepository() { public override Task Load( int topicId, Topic? referenceTopic = null, - bool isRecursive = true, - TopicPayload payload = TopicPayload.All + bool isRecursive = false, + TopicPayload payload = TopicPayload.None ) { /*-------------------------------------------------------------------------------------------------------------------------- @@ -76,8 +76,8 @@ public StubTopicRepository() { public override Task Load( string uniqueKey, Topic? referenceTopic = null, - bool isRecursive = true, - TopicPayload payload = TopicPayload.All + bool isRecursive = false, + TopicPayload payload = TopicPayload.None ) { /*-------------------------------------------------------------------------------------------------------------------------- diff --git a/OnTopic.AspNetCore.Mvc.Tests/TestDoubles/TestTopicRepository.cs b/OnTopic.AspNetCore.Mvc.Tests/TestDoubles/TestTopicRepository.cs index 034e553d..e3a613e4 100644 --- a/OnTopic.AspNetCore.Mvc.Tests/TestDoubles/TestTopicRepository.cs +++ b/OnTopic.AspNetCore.Mvc.Tests/TestDoubles/TestTopicRepository.cs @@ -49,8 +49,8 @@ public TestTopicRepository() { public override Task Load( string uniqueKey, Topic? referenceTopic = null, - bool isRecursive = true, - TopicPayload payload = TopicPayload.All + bool isRecursive = false, + TopicPayload payload = TopicPayload.None ) => Task.FromResult(String.IsNullOrEmpty(uniqueKey)? null : _cache.FindFirst(t => t.GetUniqueKey() == uniqueKey)); /*============================================================================================================================ diff --git a/OnTopic.Data.Caching/CachedTopicRepository.cs b/OnTopic.Data.Caching/CachedTopicRepository.cs index 6a637907..8b4af01b 100644 --- a/OnTopic.Data.Caching/CachedTopicRepository.cs +++ b/OnTopic.Data.Caching/CachedTopicRepository.cs @@ -94,8 +94,8 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos public override async Task Load( int topicId, Topic? referenceTopic = null, - bool isRecursive = true, - TopicPayload payload = TopicPayload.All + bool isRecursive = false, + TopicPayload payload = TopicPayload.None ) { /*-------------------------------------------------------------------------------------------------------------------------- @@ -159,8 +159,8 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos public override async Task Load( string uniqueKey, Topic? referenceTopic = null, - bool isRecursive = true, - TopicPayload payload = TopicPayload.All + bool isRecursive = false, + TopicPayload payload = TopicPayload.None ) { /*-------------------------------------------------------------------------------------------------------------------------- diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index c440a753..3c79d770 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -58,8 +58,8 @@ public SqlTopicRepository(string connectionString) { public override async Task Load( string uniqueKey, Topic? referenceTopic = null, - bool isRecursive = true, - TopicPayload payload = TopicPayload.All + bool isRecursive = false, + TopicPayload payload = TopicPayload.None ) { /*-------------------------------------------------------------------------------------------------------------------------- @@ -121,8 +121,8 @@ public SqlTopicRepository(string connectionString) { public override async Task Load( int topicId, Topic? referenceTopic = null, - bool isRecursive = true, - TopicPayload payload = TopicPayload.All + bool isRecursive = false, + TopicPayload payload = TopicPayload.None ) { /*-------------------------------------------------------------------------------------------------------------------------- diff --git a/OnTopic.TestDoubles/DummyTopicRepository.cs b/OnTopic.TestDoubles/DummyTopicRepository.cs index 903c2faa..9e176590 100644 --- a/OnTopic.TestDoubles/DummyTopicRepository.cs +++ b/OnTopic.TestDoubles/DummyTopicRepository.cs @@ -39,16 +39,16 @@ public DummyTopicRepository() { } public override Task Load( int topicId, Topic? referenceTopic = null, - bool isRecursive = true, - TopicPayload payload = TopicPayload.All + bool isRecursive = false, + TopicPayload payload = TopicPayload.None ) => Task.FromResult(null); /// public override Task Load( string uniqueKey, Topic? referenceTopic = null, - bool isRecursive = true, - TopicPayload payload = TopicPayload.All + bool isRecursive = false, + TopicPayload payload = TopicPayload.None ) => Task.FromResult(null); /// diff --git a/OnTopic.TestDoubles/StubTopicRepository.cs b/OnTopic.TestDoubles/StubTopicRepository.cs index 64ee2daf..f85ef7b2 100644 --- a/OnTopic.TestDoubles/StubTopicRepository.cs +++ b/OnTopic.TestDoubles/StubTopicRepository.cs @@ -50,8 +50,8 @@ public StubTopicRepository() { public override Task Load( int topicId, Topic? referenceTopic = null, - bool isRecursive = true, - TopicPayload payload = TopicPayload.All + bool isRecursive = false, + TopicPayload payload = TopicPayload.None ) { /*-------------------------------------------------------------------------------------------------------------------------- @@ -81,8 +81,8 @@ public StubTopicRepository() { public override Task Load( string uniqueKey, Topic? referenceTopic = null, - bool isRecursive = true, - TopicPayload payload = TopicPayload.All + bool isRecursive = false, + TopicPayload payload = TopicPayload.None ) { /*-------------------------------------------------------------------------------------------------------------------------- diff --git a/OnTopic/Repositories/ITopicRepository.cs b/OnTopic/Repositories/ITopicRepository.cs index 5f8b1a44..97c7bf1c 100644 --- a/OnTopic/Repositories/ITopicRepository.cs +++ b/OnTopic/Repositories/ITopicRepository.cs @@ -89,7 +89,8 @@ public interface ITopicRepository { \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Loads the entire root topic graph, including all descendants. + /// Loads the root , using the same lazy defaults as . /// /// A topic object. public Task Load() => Load(-1); @@ -111,8 +112,8 @@ public interface ITopicRepository { Task Load( int topicId, Topic? referenceTopic = null, - bool isRecursive = true, - TopicPayload payload = TopicPayload.All + bool isRecursive = false, + TopicPayload payload = TopicPayload.None ); /// @@ -134,8 +135,8 @@ public interface ITopicRepository { Task Load( string uniqueKey, Topic? referenceTopic = null, - bool isRecursive = true, - TopicPayload payload = TopicPayload.All + bool isRecursive = false, + TopicPayload payload = TopicPayload.None ); /// diff --git a/OnTopic/Repositories/ObservableTopicRepository.cs b/OnTopic/Repositories/ObservableTopicRepository.cs index 986868a8..6ceba8b1 100644 --- a/OnTopic/Repositories/ObservableTopicRepository.cs +++ b/OnTopic/Repositories/ObservableTopicRepository.cs @@ -215,16 +215,16 @@ public event EventHandler? TopicRenamed { public abstract Task Load( int topicId, Topic? referenceTopic = null, - bool isRecursive = true, - TopicPayload payload = TopicPayload.All + bool isRecursive = false, + TopicPayload payload = TopicPayload.None ); /// public abstract Task Load( string uniqueKey, Topic? referenceTopic = null, - bool isRecursive = true, - TopicPayload payload = TopicPayload.All + bool isRecursive = false, + TopicPayload payload = TopicPayload.None ); /// diff --git a/OnTopic/Repositories/TopicPayload.cs b/OnTopic/Repositories/TopicPayload.cs index a7183ae2..f05b2ba5 100644 --- a/OnTopic/Repositories/TopicPayload.cs +++ b/OnTopic/Repositories/TopicPayload.cs @@ -17,6 +17,12 @@ namespace OnTopic.Repositories; /// /// , , , , and /// all have lazy-loading fill paths via . +/// +/// The default value for all Load overloads is , so lazy loading +/// is the default: Each boundary is fetched on demand via its autoloading accessor or an explicit EnsureLoaded call. +/// Callers that need everything up front may still request explicitly. Indexed attributes are always +/// returned as part of the base graph and are not a separately lazy-loadable boundary. +/// /// [Flags] public enum TopicPayload { diff --git a/OnTopic/Repositories/TopicRepositoryDecorator.cs b/OnTopic/Repositories/TopicRepositoryDecorator.cs index f14c0304..da27e36e 100644 --- a/OnTopic/Repositories/TopicRepositoryDecorator.cs +++ b/OnTopic/Repositories/TopicRepositoryDecorator.cs @@ -83,8 +83,8 @@ protected TopicRepositoryDecorator(ITopicRepository topicRepository) { public override Task Load( int topicId, Topic? referenceTopic = null, - bool isRecursive = true, - TopicPayload payload = TopicPayload.All + bool isRecursive = false, + TopicPayload payload = TopicPayload.None ) => TopicRepository.Load(topicId, referenceTopic, isRecursive, payload); @@ -92,8 +92,8 @@ protected TopicRepositoryDecorator(ITopicRepository topicRepository) { public override Task Load( string uniqueKey, Topic? referenceTopic = null, - bool isRecursive = true, - TopicPayload payload = TopicPayload.All + bool isRecursive = false, + TopicPayload payload = TopicPayload.None ) => TopicRepository.Load(uniqueKey, referenceTopic, isRecursive, payload); From 864d7126a9d743d4ae742bd559df5810887e4d16 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Mon, 13 Jul 2026 22:40:11 -0700 Subject: [PATCH 156/337] Introduced `TopicRecord` for testing This keeps track of the barebones metadata associated with a topic. It will be used to quickly and easily define topics without much ceremony, and then "materialized" into real topics by a forthcoming `StubLazyLoadingTopicRepositoryBuilder`. This establishes a core element for genuine testing of the lazy-loading project (#111), which has previously only tested eagerly loaded topic graphs via `StubTopicRepository` to evaluate `LoadState`, `IsLoaded()`, and `SetLoadState()`, but not the actual lazy-loading functionality of `EnsureLoaded()`. --- .../LazyLoading/TopicRecord.cs | 37 +++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 OnTopic.TestDoubles/LazyLoading/TopicRecord.cs diff --git a/OnTopic.TestDoubles/LazyLoading/TopicRecord.cs b/OnTopic.TestDoubles/LazyLoading/TopicRecord.cs new file mode 100644 index 00000000..31439e76 --- /dev/null +++ b/OnTopic.TestDoubles/LazyLoading/TopicRecord.cs @@ -0,0 +1,37 @@ +/*============================================================================================================================== +| Author Ignia, LLC +| Client Ignia, LLC +| Project Topics Library +\=============================================================================================================================*/ + +namespace OnTopic.TestDoubles.LazyLoading; + +/*============================================================================================================================== +| RECORD: TOPIC RECORD +\-----------------------------------------------------------------------------------------------------------------------------*/ +/// +/// Represents a single topic within 's flat, SQL-free record store, from which +/// shallow instances are built and lazily materialized. +/// +/// The topic's unique identifier. +/// The topic's key. +/// The topic's content type. +/// +/// The identifier of the topic's parent, or null if the topic is a top-level "content" topic, attached directly under +/// Root. +/// +/// Attribute values always present on the topic, regardless of requested payload. +/// Attribute values only merged when the extended-attribute property is materialized. +/// Relationship key/id pairs, deferred until the relationship property is materialized. +/// Reference key/id pairs, deferred until the reference property is materialized. +[ExcludeFromCodeCoverage] +public sealed record TopicRecord( + int Id, + string Key, + string ContentType, + int? ParentId, + IReadOnlyDictionary IndexedAttributes, + IReadOnlyDictionary ExtendedAttributes, + IReadOnlyList<(string Key, int TargetId)> Relationships, + IReadOnlyList<(string Key, int TargetId)> References +); \ No newline at end of file From 198ae0954bfe611949695121a4cbdc24f21f4900 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Mon, 13 Jul 2026 22:40:39 -0700 Subject: [PATCH 157/337] Introduced `StubLazyLoadingTopicRepositoryBuilder` The `StubLazyLoadingTopicRepositoryBuilder` provides a fluent interface for converting easily assembled `TopicRecord` instances (864d7126) into actual `Topic` instances, with their appropriate properties loaded. This will be used by a forthcoming `StubLazyLoadingTopicRepository`, as the name suggests, which is the core test double for lazy loading. This establishes a core element for genuine testing of the lazy-loading project (#111), which has previously only tested eagerly loaded topic graphs via `StubTopicRepository` to evaluate `LoadState`, `IsLoaded()`, and `SetLoadState()`, but not the actual lazy-loading functionality of `EnsureLoaded()`. --- .../StubLazyLoadingTopicRepositoryBuilder.cs | 123 ++++++++++++++++++ 1 file changed, 123 insertions(+) create mode 100644 OnTopic.TestDoubles/LazyLoading/StubLazyLoadingTopicRepositoryBuilder.cs diff --git a/OnTopic.TestDoubles/LazyLoading/StubLazyLoadingTopicRepositoryBuilder.cs b/OnTopic.TestDoubles/LazyLoading/StubLazyLoadingTopicRepositoryBuilder.cs new file mode 100644 index 00000000..51171523 --- /dev/null +++ b/OnTopic.TestDoubles/LazyLoading/StubLazyLoadingTopicRepositoryBuilder.cs @@ -0,0 +1,123 @@ +/*============================================================================================================================== +| Author Ignia, LLC +| Client Ignia, LLC +| Project Topics Library +\=============================================================================================================================*/ + +namespace OnTopic.TestDoubles.LazyLoading; + +/*============================================================================================================================== +| CLASS: STUB LAZY LOADING TOPIC REPOSITORY BUILDER +\-----------------------------------------------------------------------------------------------------------------------------*/ +/// +/// Provides a fluent builder for constructing a custom set to seed a , sparing downstream consumers from manually authoring records or rebuilding this +/// scaffolding. +/// +[ExcludeFromCodeCoverage] +public sealed class StubLazyLoadingTopicRepositoryBuilder { + + /*============================================================================================================================ + | CLASS: STAGING RECORD + \---------------------------------------------------------------------------------------------------------------------------*/ + private sealed class StagingRecord(string key, string contentType, int? parentId) { + public string Key { get; } = key; + public string ContentType { get; } = contentType; + public int? ParentId { get; } = parentId; + public Dictionary IndexedAttributes { get; } = []; + public Dictionary ExtendedAttributes { get; } = []; + public List<(string Key, int TargetId)> Relationships { get; } = []; + public List<(string Key, int TargetId)> References { get; } = []; + } + + /*============================================================================================================================ + | PRIVATE VARIABLES + \---------------------------------------------------------------------------------------------------------------------------*/ + private readonly Dictionary _staging = []; + private readonly List _order = []; + + /*============================================================================================================================ + | METHOD: ADD TOPIC + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Adds a new to the set being built. + /// + /// The topic's unique identifier. + /// The topic's key. + /// The topic's content type. + /// The identifier of the topic's parent, or null to attach directly under Root. + /// Attribute values always present on the topic. + /// Attribute values only present once the extended attributes are loaded. + public StubLazyLoadingTopicRepositoryBuilder AddTopic( + int id, + string key, + string contentType, + int? parentId, + IReadOnlyDictionary? indexedAttributes = null, + IReadOnlyDictionary? extendedAttributes = null + ) { + var staging = new StagingRecord(key, contentType, parentId); + if (indexedAttributes is not null) { + foreach (var attribute in indexedAttributes) { + staging.IndexedAttributes[attribute.Key] = attribute.Value; + } + } + if (extendedAttributes is not null) { + foreach (var attribute in extendedAttributes) { + staging.ExtendedAttributes[attribute.Key] = attribute.Value; + } + } + _staging[id] = staging; + _order.Add(id); + return this; + } + + /*============================================================================================================================ + | METHOD: ADD RELATIONSHIP + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Adds a relationship from the topic previously added via under to + /// , under . The target need not itself be present in the record store: + /// An absent target id produces a stale, unresolvable relationship, useful for exercising discard behavior. + /// + public StubLazyLoadingTopicRepositoryBuilder AddRelationship(int sourceId, string key, int targetId) { + _staging[sourceId].Relationships.Add((key, targetId)); + return this; + } + + /*============================================================================================================================ + | METHOD: ADD REFERENCE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Adds a reference from the topic previously added via under to + /// , under . The target need not itself be present in the record store: + /// An absent target id produces a stale, unresolvable reference, useful for exercising discard behavior. + /// + public StubLazyLoadingTopicRepositoryBuilder AddReference(int sourceId, string key, int targetId) { + _staging[sourceId].References.Add((key, targetId)); + return this; + } + + /*============================================================================================================================ + | METHOD: BUILD + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Finalizes the set of s built so far into an immutable list, suitable for passing to . + /// + public IReadOnlyList Build() => + _order.Select(id => { + var staging = _staging[id]; + return new TopicRecord( + id, + staging.Key, + staging.ContentType, + staging.ParentId, + new Dictionary(staging.IndexedAttributes), + new Dictionary(staging.ExtendedAttributes), + staging.Relationships.ToArray(), + staging.References.ToArray() + ); + }).ToList(); + +} //Class \ No newline at end of file From aa2c4764387d930cd83e424fc24bd08d583d6384 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Mon, 13 Jul 2026 22:41:56 -0700 Subject: [PATCH 158/337] Introduced `StubLazyLoadingTopicRepository` Taking advantages of the previously introduced `StubLazyLoadingTopicRepositoryBuilder` (198ae095), the `StubLazyLoadingTopicRepository` offers actual partial-loading and lazy-loading. This establishes the core test double for genuine testing of the lazy-loading project (#111), which has previously only tested eagerly loaded topic graphs via `StubTopicRepository` to evaluate `LoadState`, `IsLoaded()`, and `SetLoadState()`, but not the actual lazy-loading functionality of `EnsureLoaded()`. --- .../StubLazyLoadingTopicRepository.cs | 599 ++++++++++++++++++ 1 file changed, 599 insertions(+) create mode 100644 OnTopic.TestDoubles/LazyLoading/StubLazyLoadingTopicRepository.cs diff --git a/OnTopic.TestDoubles/LazyLoading/StubLazyLoadingTopicRepository.cs b/OnTopic.TestDoubles/LazyLoading/StubLazyLoadingTopicRepository.cs new file mode 100644 index 00000000..f44956c6 --- /dev/null +++ b/OnTopic.TestDoubles/LazyLoading/StubLazyLoadingTopicRepository.cs @@ -0,0 +1,599 @@ +/*============================================================================================================================== +| Author Ignia, LLC +| Client Ignia, LLC +| Project Topics Library +\=============================================================================================================================*/ +using OnTopic.Internal.Diagnostics; +using OnTopic.Querying; +using OnTopic.Repositories; + +namespace OnTopic.TestDoubles.LazyLoading; + +/*============================================================================================================================== +| CLASS: STUB LAZY TOPIC DATA REPOSITORY +\-----------------------------------------------------------------------------------------------------------------------------*/ +/// +/// Provides a lazy-loading implementation of an , serving partially loaded topics with the +/// ability to be dynamically filled by e.g., . +/// +/// +/// +/// Unlike , which serves a fully materialized graph from the outset, this double +/// builds each shallow: Its own , , and association properties are absent until something fills them, one +/// at a time, from the record store. +/// +/// +/// Filling happens two ways, matching how a real, e.g., SQL-backed repository distinguishes a batch Load() from an +/// on-demand fill. and its overloads only connect association +/// targets already present in the graph being built, leaving the rest deferred; it never issues an additional fetch to +/// resolve a missing target. , invoked either explicitly +/// or via one of 's autoloading getters, goes further: It recursively loads whatever deferred targets it +/// can find and discards the rest as stale. +/// +/// +/// The Root:Configuration subtree (required by for content type +/// resolution) is the one exception to lazy service: It is built eagerly, with every property , exactly as production seeds it. Everything else is served lazily from the record store supplied to the constructor, +/// or from if none is supplied. +/// +/// +/// A per-topic, per-property fetch-count spy ( and ) records every fill, letting tests assert fetch-once behavior and, critically, that stamping the resolver doesn't +/// trigger lazy loading. +/// +/// +[ExcludeFromCodeCoverage] +public class StubLazyLoadingTopicRepository : TopicRepository, ITopicRepository, ITopicLoadResolver { + + /*============================================================================================================================ + | VARIABLES + \---------------------------------------------------------------------------------------------------------------------------*/ + private readonly Topic _root; + private readonly Dictionary _served = []; + private readonly Dictionary _keyIndex = new(StringComparer.OrdinalIgnoreCase); + private int _identity = 90000; + + private readonly IReadOnlyDictionary _store; + private readonly Dictionary<(int TopicId, TopicPayload Boundary), int> _fetchCounts = []; + + /*============================================================================================================================ + | CONSTRUCTOR + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Instantiates a new instance of the using the default, built-in seed dataset. + /// + public StubLazyLoadingTopicRepository() : this(CreateDefaultRecords()) { } + + /// + /// Instantiates a new instance of the using a custom set of s, allowing downstream consumers (e.g., the OnTopic Editor) to seed their own lazy-capable content graph + /// without rebuilding this scaffolding. See for a convenient way to construct + /// . + /// + /// The flat, SQL-free record store from which the "content" subtree is lazily served. + public StubLazyLoadingTopicRepository(IEnumerable records) { + + Contract.Requires(records, nameof(records)); + + /*-------------------------------------------------------------------------------------------------------------------------- + | Eagerly build the Root:Configuration scaffold; every boundary defaults to Loaded, since it is never marked otherwise + \-------------------------------------------------------------------------------------------------------------------------*/ + _root = BuildEagerScaffold(); + + foreach (var topic in _root.FindAll()) { + _served[topic.Id] = topic; + _keyIndex[topic.GetUniqueKey()] = topic.Id; + } + + /*-------------------------------------------------------------------------------------------------------------------------- + | Index the lazy content record store + \-------------------------------------------------------------------------------------------------------------------------*/ + _store = records.ToDictionary(record => record.Id); + + foreach (var record in _store.Values) { + _keyIndex[GetUniqueKey(record)] = record.Id; + } + + } + + /*============================================================================================================================ + | METHOD: BUILD EAGER SCAFFOLD + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Builds the minimal Root:Configuration scaffold that requires + /// for construction (content-type resolution) and that requires for Save() + /// (content-type validation). + /// + private static Topic BuildEagerScaffold() { + + var root = new Topic("Root", "Container", null, 1); + var configuration = new Topic("Configuration", "Container", root, 2); + var contentTypes = new ContentTypeDescriptor("ContentTypes", "ContentTypeDescriptor", configuration, 3); + _ = new ContentTypeDescriptor("Page", "ContentTypeDescriptor", contentTypes, 4); + + return root; + + } + + /*============================================================================================================================ + | METHOD: LOAD + \---------------------------------------------------------------------------------------------------------------------------*/ + + /// + public override async Task Load( + string uniqueKey, + Topic? referenceTopic = null, + bool isRecursive = false, + TopicPayload payload = TopicPayload.None + ) { + + // Validate unique key + if (String.IsNullOrEmpty(uniqueKey)) { + return null; + } + + // Normalize unique key by ensuring "root:" prefix + if (!uniqueKey.StartsWith(_root.Key, StringComparison.OrdinalIgnoreCase)) { + uniqueKey = $"{_root.Key}:{uniqueKey.TrimStart(':')}"; + } + + // If the root is requested, hardcode the topicId at -1 + if (uniqueKey.Equals(_root.Key, StringComparison.OrdinalIgnoreCase)) { + return await Load(-1, referenceTopic, isRecursive, payload).ConfigureAwait(false); + } + + // If the unique key isn't in the data store, return null + if (!_keyIndex.TryGetValue(uniqueKey, out var topicId)) { + return null; + } + + // Otherwise, use the store's topicId to call the base overload + return await Load(topicId, referenceTopic, isRecursive, payload).ConfigureAwait(false); + + } + + /// + /// + /// Returns an already- topic, without raising + /// again: The event fires only when a topic is genuinely built for the first time, mirroring how a real repository only + /// fires when something is actually pulled from the persistence store. On a miss against the record store, builds the + /// requested topic and its ancestor chain as shallow, sparse topics, and raises the event for the requested topic. Either + /// way, if requests anything not yet loaded, it connects whatever it can from the graph already + /// built so far via ; targets that aren't yet resident stay deferred. + /// + public override async Task Load( + int topicId, + Topic? referenceTopic = null, + bool isRecursive = false, + TopicPayload payload = TopicPayload.None + ) { + + // Setup + var topic = (Topic?)null; + var isNewlyBuilt = false; + + // Attempt to retrieve topic, falling back to the topic store if needed + if (topicId < 0) { + topic = _root; + } + else if (_served.TryGetValue(topicId, out var existing)) { + topic = existing; + } + else if (_store.TryGetValue(topicId, out var record)) { + topic = BuildTopicWithAncestors(record); + isNewlyBuilt = true; + } + else { + return null; + } + + // Preload the topic with the requested payload + await FillRequestedPayload(topic, payload, resolveDeferredTargets: false, CancellationToken.None).ConfigureAwait(false); + + // Fire the TopicLoaded event, if newly built + if (isNewlyBuilt) { + OnTopicLoaded(new(topic, isRecursive)); + } + + // Return the requested topic + return topic; + + } + + /// + public override async Task Load(int topicId, DateTime version, Topic? referenceTopic = null) { + + // Setup + Contract.Requires(version.Date < DateTime.UtcNow, "The version requested must be a valid historical date."); + Contract.Requires( + version.Date > new DateTime(2014, 12, 9), + "The version is expected to have been created since version support was introduced into the topic library." + ); + + // Load the topic requested + var topic = await Load(topicId, referenceTopic).ConfigureAwait(false); + + // Throw an exception if the topic doesn't exist + if (topic is null) { + throw new TopicNotFoundException(topicId); + } + + // For the stub, accept whatever version is provided + if (!topic.VersionHistory.Contains(version)) { + topic.VersionHistory.Add(version); + } + topic.LastModified = version; + + // Fire the TopicLoaded event; this is always assumed to be freshly loaded + OnTopicLoaded(new(topic, false, version)); + + // Return the topic version + return topic; + + } + + /*============================================================================================================================ + | METHOD: REFRESH + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + public override Task Refresh(Topic referenceTopic, DateTime since) => Task.CompletedTask; + + /*============================================================================================================================ + | METHOD: SAVE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + protected override Task SaveTopic([NotNull]Topic topic, DateTime version, bool persistRelationships) { + + // For saving topics, just assign an identity + if (topic.IsNew) { + topic.Id = _identity++; + } + + return Task.CompletedTask; + + } + + /*============================================================================================================================ + | METHOD: MOVE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + protected override Task MoveTopic(Topic topic, Topic target, Topic? sibling = null) => Task.CompletedTask; + + /*============================================================================================================================ + | METHOD: DELETE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + protected override Task DeleteTopic(Topic topic) => Task.CompletedTask; + + /*============================================================================================================================ + | METHODS: TOPIC LOAD RESOLVER + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// + /// The on-demand fill: Unlike , this recursively resolves deferred + /// relationship and reference targets via the inherited ResolveDeferredAssociations, discarding whatever remains + /// unresolved as stale, assuming either or . + /// + public virtual async Task EnsureLoaded(Topic topic, TopicPayload payload, CancellationToken cancellationToken = default) { + + // Validate the input + Contract.Requires(topic, nameof(topic)); + + // There's nothing to load on a new topic + if (topic.IsNew) { + return; + } + + // Call the centralized private helper to fulfill the request + await FillRequestedPayload(topic, payload, resolveDeferredTargets: true, cancellationToken).ConfigureAwait(false); + + } + + /*============================================================================================================================ + | METHOD: FILL REQUESTED PAYLOAD + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// On a plain Load(), connects resident relationship and reference targets unconditionally, regardless of + /// . Either way, loads the data requested in , after filtering out + /// any already flags, recording a fetch in the spy for each property filled. Children are + /// fetched from the record store one level at a time; a child already present in (e.g., attached + /// while building an ancestor chain for a deeper call) is + /// reused rather than rebuilt, to avoid colliding with the existing instance already attached to the graph. + /// + /// The topic whose requested payload should be filled. + /// The requested flags. + /// + /// Whether unresolved relationships and references targets should be recursively loaded, via the inherited + /// ResolveDeferredAssociations. Set by 's on-demand + /// fill; left by a plain Load(), which only connects targets already present in the graph, + /// via . + /// + /// An optional token used only when resolving deferred targets. + private async Task FillRequestedPayload( + Topic topic, + TopicPayload payload, + bool resolveDeferredTargets, + CancellationToken cancellationToken + ) { + + /*-------------------------------------------------------------------------------------------------------------------------- + | Setup + \-------------------------------------------------------------------------------------------------------------------------*/ + var rawTopic = (ITopicBackingAccessor)topic; + + /*-------------------------------------------------------------------------------------------------------------------------- + | Relationships and references: Connect resident targets + >------------------------------------------------------------------------------------------------------------------------- + | Unconditionally connects targets already present in the graph, mirroring how LoadTopicGraph() reads relationship and + | reference rows alongside every topic row and links whatever's already resident, regardless of the requested payload. + | Runs ahead of the payload/store checks below, since it isn't gated by them in production either. + \-------------------------------------------------------------------------------------------------------------------------*/ + if (!resolveDeferredTargets) { + ConnectResidentAssociations(rawTopic); + } + + /*-------------------------------------------------------------------------------------------------------------------------- + | Filter out any already loaded payloads + \-------------------------------------------------------------------------------------------------------------------------*/ + payload = topic.FilterPayload(payload); + + if (payload is TopicPayload.None) { + return; + } + + // Filters out just the association payloads, if present, for a later gate + var associationPayload = payload & (TopicPayload.Relationships | TopicPayload.References); + + /*-------------------------------------------------------------------------------------------------------------------------- + | A topic with pending payload must be backed by a record + >--------------------------------------------------------------------------------------------------------------------------- + | A topic that has no corresponding record means it was attached to the graph without ever being built from the store, which + | this stub has no way to fulfill; this represents test setup error, not a legitimate state + \-------------------------------------------------------------------------------------------------------------------------*/ + _store.TryGetValue(topic.Id, out var record); + Contract.Assume( + record, + $"{nameof(StubLazyLoadingTopicRepository)} can only lazily fill topics that are defined in the record store supplied to its " + + $"constructor. Topic {topic.Id} was attached to the graph with a pending {payload} payload, but has no corresponding " + + $"record to fill it from. This is an invalid configuration." + ); + + /*-------------------------------------------------------------------------------------------------------------------------- + | Children + \-------------------------------------------------------------------------------------------------------------------------*/ + if (payload.HasFlag(TopicPayload.Children)) { + + // Loop through each child record and build the topic from the topic store + foreach (var childRecord in _store.Values.Where(r => r.ParentId == topic.Id).OrderBy(r => r.Id)) { + + // Build the child record, assuming it hasn't already been served + if (_served.ContainsKey(childRecord.Id)) { + continue; + } + var child = BuildTopic(childRecord, topic); + + // Load the rest of the requested payload for the child, mirroring how a Children fetch also pulls in whatever else was + // requested (e.g., ExtendedAttributes, VersionHistory) for the whole scope, while relationships and references always + // ride along for free; the child's own Children are left deferred + var childPayload = (payload & ~TopicPayload.Children) | TopicPayload.Relationships | TopicPayload.References; + await FillRequestedPayload(child, childPayload, resolveDeferredTargets: false, cancellationToken).ConfigureAwait(false); + + // Fire the TopicLoaded event + OnTopicLoaded(new(child, isRecursive: false)); + + } + + // Mark the children as fetched and loaded + RecordFetch(topic.Id, TopicPayload.Children); + topic.SetLoadState(TopicPayload.Children, LoadState.Loaded); + + } + + /*-------------------------------------------------------------------------------------------------------------------------- + | Extended attributes + \-------------------------------------------------------------------------------------------------------------------------*/ + if (payload.HasFlag(TopicPayload.ExtendedAttributes)) { + + // Load each of the extended attributes from the data store + foreach (var attribute in record.ExtendedAttributes) { + rawTopic.Attributes.SetValue(attribute.Key, attribute.Value, markDirty: false, isExtendedAttribute: true); + } + + // Mark the extended attributes as fetched and loaded + RecordFetch(topic.Id, TopicPayload.ExtendedAttributes); + topic.SetLoadState(TopicPayload.ExtendedAttributes, LoadState.Loaded); + + } + + /*-------------------------------------------------------------------------------------------------------------------------- + | Relationships and references: Resolve deferred targets + >------------------------------------------------------------------------------------------------------------------------- + | Gated on what was actually requested, and delegates to the inherited ResolveDeferredAssociations, so this double + | utilizes that shared infrastructure. Resident targets were already connected above, regardless of this gate. + \-------------------------------------------------------------------------------------------------------------------------*/ + if (resolveDeferredTargets && associationPayload is not TopicPayload.None) { + + // Load any deferred relationships or references + await ResolveDeferredAssociations(topic, associationPayload, cancellationToken).ConfigureAwait(false); + + // Mark the associations requested as fetched + if (associationPayload.HasFlag(TopicPayload.Relationships)) { + RecordFetch(topic.Id, TopicPayload.Relationships); + } + if (associationPayload.HasFlag(TopicPayload.References)) { + RecordFetch(topic.Id, TopicPayload.References); + } + + } + + } + + /*============================================================================================================================ + | METHOD: CONNECT RESIDENT ASSOCIATIONS + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Connects each deferred relationship or reference entry whose target is already present in , without + /// recursively loading anything. Mirrors how a real, SQL-backed repository connects association targets found within the + /// same result set as the requested topic, leaving out-of-scope targets deferred for a later, explicit fill via . + /// + /// The requesting topic's backing accessor. + private void ConnectResidentAssociations(ITopicBackingAccessor rawTopic) { + + // Attempts to resolve each deferred relationship + foreach (var entry in rawTopic.Relationships.Deferred.ToArray()) { + if (_served.TryGetValue(entry.TopicId, out var target)) { + rawTopic.Relationships.SetValue(entry.Key, target, markDirty: false); + } + } + + // Attempts to resolve each deferred reference + foreach (var entry in rawTopic.References.Deferred.ToArray()) { + if (_served.TryGetValue(entry.TopicId, out var target)) { + rawTopic.References.SetValue(entry.Key, target, markDirty: false); + } + } + + } + + /*============================================================================================================================ + | METHOD: BUILD TOPIC WITH ANCESTORS + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Builds the requested as a shallow, served , first building (or reusing) + /// its entire ancestor chain up to . + /// + private Topic BuildTopicWithAncestors(TopicRecord record) { + var parent = record.ParentId is { } parentId ? GetOrBuildAncestor(parentId) : _root; + return BuildTopic(record, parent); + } + + /*============================================================================================================================ + | METHOD: GET OR BUILD ANCESTOR + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Returns the already- ancestor for , or builds it and, recursively, its + /// own ancestors, as a shallow topic. Never raises : Only the + /// originally requested topic does that; ascendants are stamped separately, via StampAscendants. + /// + private Topic GetOrBuildAncestor(int topicId) { + if (_served.TryGetValue(topicId, out var existing)) { + return existing; + } + var record = _store[topicId]; + var parent = record.ParentId is { } parentId ? GetOrBuildAncestor(parentId) : _root; + return BuildTopic(record, parent); + } + + /*============================================================================================================================ + | METHOD: BUILD TOPIC + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Constructs a single shallow for under , populates + /// its indexed attributes, marks its extended attribute, children, and association properties as , and registers it in . + /// + private Topic BuildTopic(TopicRecord record, Topic parent) { + + // Setup + var topic = new Topic(record.Key, record.ContentType, parent, record.Id); + var rawTopic = (ITopicBackingAccessor)topic; + + // Set indexed attributes + foreach (var attribute in record.IndexedAttributes) { + rawTopic.Attributes.SetValue(attribute.Key, attribute.Value, markDirty: false, isExtendedAttribute: false); + } + + // Set extended attributes + topic.SetLoadState(TopicPayload.ExtendedAttributes, LoadState.NotLoaded); + + // Set children + topic.SetLoadState(TopicPayload.Children, LoadState.NotLoaded); + + // Add relationships to Deferred + foreach (var (key, targetId) in record.Relationships) { + rawTopic.Relationships.Deferred.Add(new(key, targetId)); + } + + // Add references to Deferred + foreach (var (key, targetId) in record.References) { + rawTopic.References.Deferred.Add(new(key, targetId)); + } + + // Mark record as served so it doesn't trigger OnTopicLoaded() again + _served[record.Id] = topic; + + // Return the built topic + return topic; + + } + + /*============================================================================================================================ + | METHOD: GET UNIQUE KEY + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Computes the unique key for by walking its chain through + /// the record store, without constructing or touching any instance. + /// + private string GetUniqueKey(TopicRecord record) { + List segments = [record.Key]; + var current = record; + while (current.ParentId is { } parentId) { + current = _store[parentId]; + segments.Insert(0, current.Key); + } + segments.Insert(0, _root.Key); + return String.Join(":", segments); + } + + /*============================================================================================================================ + | METHODS: FETCH SPY + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Returns the total number of genuine boundary fetches recorded across every topic. + /// + public int TotalFetches => _fetchCounts.Values.Sum(); + + /// + /// Returns the number of times was genuinely fetched for . + /// + public int GetFetchCount(int topicId, TopicPayload boundary) => _fetchCounts.GetValueOrDefault((topicId, boundary), 0); + + /// + /// Increments the fetch-count spy for on . + /// + private void RecordFetch(int topicId, TopicPayload boundary) { + var key = (topicId, boundary); + _fetchCounts[key] = _fetchCounts.GetValueOrDefault(key) + 1; + } + + /*============================================================================================================================ + | METHOD: CREATE DEFAULT RECORDS + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Creates the built-in seed dataset used by the parameterless constructor: A four-level "Web" content subtree with an + /// extended-attribute topic, a resolvable relationship and reference pair, and a stale (dangling) relationship and + /// reference pair. + /// + private static IReadOnlyList CreateDefaultRecords() => + new StubLazyLoadingTopicRepositoryBuilder() + .AddTopic(10000, "Web", "Page", null, indexedAttributes: new Dictionary { ["Title"] = "Web" }) + .AddTopic(10001, "Web_0", "Page", 10000, indexedAttributes: new Dictionary { ["Title"] = "Web_0" }) + .AddTopic( + 10002, + "Web_0_0", + "Page", + 10001, + indexedAttributes: new Dictionary { ["Title"] = "Web_0_0" }, + extendedAttributes: new Dictionary { ["Body"] = "Extended body content for Web_0_0." } + ) + .AddTopic(10003, "Web_0_0_0", "Page", 10002, indexedAttributes: new Dictionary { ["Title"] = "Web_0_0_0" }) + .AddTopic(10004, "Web_1", "Page", 10000, indexedAttributes: new Dictionary { ["Title"] = "Web_1" }) + .AddRelationship(10004, "Related", 10002) + .AddRelationship(10001, "Related", 99999) + .AddReference(10004, "BaseTopic", 10001) + .AddReference(10001, "BaseTopic", 99998) + .Build(); + +} //Class \ No newline at end of file From a159b6167127a44680a94ab6d1b78a51628a40a9 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 14 Jul 2026 01:51:10 -0700 Subject: [PATCH 159/337] Renamed `ITopicLoadResolver` to `ITopicLazyLoader` This is a more intuitive name, and more consistent with e.g., EF Core's `ILazyLoader` (which does exactly the same thing). This is a refinement for #111. --- OnTopic.Data.Caching/CachedTopicRepository.cs | 6 +++--- OnTopic.Data.Sql/SqlTopicRepository.cs | 6 +++--- .../StubLazyLoadingTopicRepository.cs | 6 +++--- OnTopic.TestDoubles/StubTopicRepository.cs | 4 ++-- ...oadResolver.cs => TrackingTopicLazyLoader.cs} | 10 +++++----- OnTopic.Tests/TopicRepositoryBaseTest.cs | 4 ++-- OnTopic.Tests/TopicTest.cs | 2 +- OnTopic/Associations/TopicReferenceCollection.cs | 2 +- .../Associations/TopicRelationshipMultiMap.cs | 2 +- OnTopic/Repositories/ITopicBackingAccessor.cs | 2 +- ...ITopicLoadResolver.cs => ITopicLazyLoader.cs} | 4 ++-- .../Repositories/LazyLoadingTopicRepository.cs | 16 ++++++++-------- OnTopic/Repositories/TopicPayload.cs | 4 ++-- OnTopic/Topic.cs | 4 ++-- 14 files changed, 36 insertions(+), 36 deletions(-) rename OnTopic.Tests/TestDoubles/{TrackingTopicLoadResolver.cs => TrackingTopicLazyLoader.cs} (77%) rename OnTopic/Repositories/{ITopicLoadResolver.cs => ITopicLazyLoader.cs} (96%) diff --git a/OnTopic.Data.Caching/CachedTopicRepository.cs b/OnTopic.Data.Caching/CachedTopicRepository.cs index 8b4af01b..13552d06 100644 --- a/OnTopic.Data.Caching/CachedTopicRepository.cs +++ b/OnTopic.Data.Caching/CachedTopicRepository.cs @@ -20,7 +20,7 @@ namespace OnTopic.Data.Caching; /// for an actual data access class. /// -public class CachedTopicRepository : TopicRepositoryDecorator, ITopicLoadResolver { +public class CachedTopicRepository : TopicRepositoryDecorator, ITopicLazyLoader { /*============================================================================================================================ | VARIABLES @@ -247,7 +247,7 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos } /*============================================================================================================================ - | METHODS: TOPIC LOAD RESOLVER + | METHODS: TOPIC LAZY LOADER \---------------------------------------------------------------------------------------------------------------------------*/ /// @@ -276,7 +276,7 @@ public virtual async Task EnsureLoaded(Topic topic, TopicPayload payload, Cancel | them, it would do so via its own, non-cache-aware Load(), producing a duplicate Topic instance for any target that's | already present in this cache. \-------------------------------------------------------------------------------------------------------------------------*/ - if (TopicRepository is ITopicLoadResolver resolver) { + if (TopicRepository is ITopicLazyLoader resolver) { var innerPayload = payload & ~(TopicPayload.Relationships | TopicPayload.References); if (innerPayload is not TopicPayload.None) { await resolver.EnsureLoaded(topic, innerPayload, cancellationToken).ConfigureAwait(false); diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index 3c79d770..57322cbb 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -21,7 +21,7 @@ namespace OnTopic.Data.Sql; /// /// Concrete implementation of the class. /// -public class SqlTopicRepository : TopicRepository, ITopicRepository, ITopicLoadResolver { +public class SqlTopicRepository : TopicRepository, ITopicRepository, ITopicLazyLoader { /*============================================================================================================================ | PRIVATE VARIABLES @@ -370,7 +370,7 @@ public override async Task Refresh(Topic referenceTopic, DateTime since) { } /*============================================================================================================================ - | METHODS: TOPIC LOAD RESOLVER + | METHODS: TOPIC LAZY LOADER \---------------------------------------------------------------------------------------------------------------------------*/ /// @@ -814,7 +814,7 @@ protected override sealed async Task DeleteTopic(Topic topic) { | METHOD: ADD ENSURE LOADED PARAMETERS \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Configures a targeting GetTopics for use by the , + /// Configures a targeting GetTopics for use by the , /// setting the payload parameters based on the requested . /// /// diff --git a/OnTopic.TestDoubles/LazyLoading/StubLazyLoadingTopicRepository.cs b/OnTopic.TestDoubles/LazyLoading/StubLazyLoadingTopicRepository.cs index f44956c6..b6dc4e52 100644 --- a/OnTopic.TestDoubles/LazyLoading/StubLazyLoadingTopicRepository.cs +++ b/OnTopic.TestDoubles/LazyLoading/StubLazyLoadingTopicRepository.cs @@ -14,7 +14,7 @@ namespace OnTopic.TestDoubles.LazyLoading; \-----------------------------------------------------------------------------------------------------------------------------*/ /// /// Provides a lazy-loading implementation of an , serving partially loaded topics with the -/// ability to be dynamically filled by e.g., . +/// ability to be dynamically filled by e.g., . /// /// /// @@ -44,7 +44,7 @@ namespace OnTopic.TestDoubles.LazyLoading; /// /// [ExcludeFromCodeCoverage] -public class StubLazyLoadingTopicRepository : TopicRepository, ITopicRepository, ITopicLoadResolver { +public class StubLazyLoadingTopicRepository : TopicRepository, ITopicRepository, ITopicLazyLoader { /*============================================================================================================================ | VARIABLES @@ -267,7 +267,7 @@ protected override Task SaveTopic([NotNull]Topic topic, DateTime version, bool p protected override Task DeleteTopic(Topic topic) => Task.CompletedTask; /*============================================================================================================================ - | METHODS: TOPIC LOAD RESOLVER + | METHODS: TOPIC LAZY LOADER \---------------------------------------------------------------------------------------------------------------------------*/ /// /// diff --git a/OnTopic.TestDoubles/StubTopicRepository.cs b/OnTopic.TestDoubles/StubTopicRepository.cs index f85ef7b2..b54046e9 100644 --- a/OnTopic.TestDoubles/StubTopicRepository.cs +++ b/OnTopic.TestDoubles/StubTopicRepository.cs @@ -23,7 +23,7 @@ namespace OnTopic.TestDoubles; /// dependency on a live database or persistent data. /// [ExcludeFromCodeCoverage] -public class StubTopicRepository : TopicRepository, ITopicRepository, ITopicLoadResolver { +public class StubTopicRepository : TopicRepository, ITopicRepository, ITopicLazyLoader { /*============================================================================================================================ | VARIABLES @@ -180,7 +180,7 @@ protected override Task SaveTopic([NotNull]Topic topic, DateTime version, bool p } /*============================================================================================================================ - | METHODS: TOPIC LOAD RESOLVER + | METHODS: TOPIC LAZY LOADER \---------------------------------------------------------------------------------------------------------------------------*/ /// /// diff --git a/OnTopic.Tests/TestDoubles/TrackingTopicLoadResolver.cs b/OnTopic.Tests/TestDoubles/TrackingTopicLazyLoader.cs similarity index 77% rename from OnTopic.Tests/TestDoubles/TrackingTopicLoadResolver.cs rename to OnTopic.Tests/TestDoubles/TrackingTopicLazyLoader.cs index 7fdfdfee..e340a958 100644 --- a/OnTopic.Tests/TestDoubles/TrackingTopicLoadResolver.cs +++ b/OnTopic.Tests/TestDoubles/TrackingTopicLazyLoader.cs @@ -8,19 +8,19 @@ namespace OnTopic.Tests.TestDoubles; /*============================================================================================================================== -| CLASS: TRACKING TOPIC LOAD RESOLVER +| CLASS: TRACKING TOPIC LAZY LOADER \-----------------------------------------------------------------------------------------------------------------------------*/ /// -/// A minimal spy that records whether it was invoked, without performing any actual loading. +/// A minimal spy that records whether it was invoked, without performing any actual loading. /// [ExcludeFromCodeCoverage] -internal sealed class TrackingTopicLoadResolver : ITopicLoadResolver { +internal sealed class TrackingTopicLazyLoader : ITopicLazyLoader { /*============================================================================================================================ | PROPERTY: WAS CALLED \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Returns if was invoked. + /// Returns if was invoked. /// public bool WasCalled { get; private set; } @@ -28,7 +28,7 @@ internal sealed class TrackingTopicLoadResolver : ITopicLoadResolver { | METHOD: ENSURE LOADED \---------------------------------------------------------------------------------------------------------------------------*/ /// - Task ITopicLoadResolver.EnsureLoaded(Topic topic, TopicPayload payload, CancellationToken cancellationToken) { + Task ITopicLazyLoader.EnsureLoaded(Topic topic, TopicPayload payload, CancellationToken cancellationToken) { WasCalled = true; return Task.CompletedTask; } diff --git a/OnTopic.Tests/TopicRepositoryBaseTest.cs b/OnTopic.Tests/TopicRepositoryBaseTest.cs index cc5e6942..70f4ba35 100644 --- a/OnTopic.Tests/TopicRepositoryBaseTest.cs +++ b/OnTopic.Tests/TopicRepositoryBaseTest.cs @@ -1139,7 +1139,7 @@ public async Task Save_TopicMovedEvent_IsRaised() { | TEST: SAVE: NEW TOPIC: STAMPS RESOLVER \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Saves a new and confirms that the repository stamps a onto it so + /// Saves a new and confirms that the repository stamps a onto it so /// that deferred boundaries can be populated on demand after the save. /// [Fact] @@ -1489,7 +1489,7 @@ public async Task EnsureLoaded_Relationships_AlreadyLoaded_SkipsFill() { /// /// Calls on a standalone instance—i.e., not /// wrapped by , and never itself passed to Load() before—for a deeply nested - /// topic, and confirms that an ascendant is nonetheless stamped with an , so its own + /// topic, and confirms that an ascendant is nonetheless stamped with an , so its own /// deferred payload can still be lazy-loaded. /// /// diff --git a/OnTopic.Tests/TopicTest.cs b/OnTopic.Tests/TopicTest.cs index 22698603..a419e9ee 100644 --- a/OnTopic.Tests/TopicTest.cs +++ b/OnTopic.Tests/TopicTest.cs @@ -564,7 +564,7 @@ public void EnsureLoaded_IsNew_DoesNotInvokeResolver() { /*-------------------------------------------------------------------------------------------------------------------------- | Establish tracking resolver \-------------------------------------------------------------------------------------------------------------------------*/ - var tracker = new TrackingTopicLoadResolver(); + var tracker = new TrackingTopicLazyLoader(); topic.Resolver = tracker; topic.Children.LoadState = LoadState.NotLoaded; diff --git a/OnTopic/Associations/TopicReferenceCollection.cs b/OnTopic/Associations/TopicReferenceCollection.cs index d99d3a96..48a8d414 100644 --- a/OnTopic/Associations/TopicReferenceCollection.cs +++ b/OnTopic/Associations/TopicReferenceCollection.cs @@ -64,7 +64,7 @@ public TopicReferenceCollection(Topic parentTopic) : base(parentTopic) { } /// /// /// Written to by the when a reference target cannot be found in the current . The resolves each entry + /// "TopicIndex"/>. The resolves each entry /// by calling the 's Load() method, assuming the topics haven't since been introduced /// to the topic graph. /// diff --git a/OnTopic/Associations/TopicRelationshipMultiMap.cs b/OnTopic/Associations/TopicRelationshipMultiMap.cs index f13e3baa..2672fa19 100644 --- a/OnTopic/Associations/TopicRelationshipMultiMap.cs +++ b/OnTopic/Associations/TopicRelationshipMultiMap.cs @@ -271,7 +271,7 @@ public void SetTopic(string relationshipKey, Topic topic, bool? isDirty, bool is /// /// /// Written to by the when a relationship target cannot be found in the current . The resolves each entry + /// "TopicIndex"/>. The resolves each entry /// by calling the 's Load() method, assuming the topics haven't since been introduced /// to the topic graph. /// diff --git a/OnTopic/Repositories/ITopicBackingAccessor.cs b/OnTopic/Repositories/ITopicBackingAccessor.cs index 52210119..8e29c923 100644 --- a/OnTopic/Repositories/ITopicBackingAccessor.cs +++ b/OnTopic/Repositories/ITopicBackingAccessor.cs @@ -18,7 +18,7 @@ namespace OnTopic.Repositories; /// /// exposes , , and as autoloading getters: Accessing them can trigger a synchronous call. Repository and resolver infrastructure that reads or +/// "ITopicLazyLoader.EnsureLoaded(Topic, TopicPayload)"/> call. Repository and resolver infrastructure that reads or /// writes these collections as part of a load or resolve operation must bypass those getters to avoid infinite loops. /// /// diff --git a/OnTopic/Repositories/ITopicLoadResolver.cs b/OnTopic/Repositories/ITopicLazyLoader.cs similarity index 96% rename from OnTopic/Repositories/ITopicLoadResolver.cs rename to OnTopic/Repositories/ITopicLazyLoader.cs index 6c4c489e..41774f9a 100644 --- a/OnTopic/Repositories/ITopicLoadResolver.cs +++ b/OnTopic/Repositories/ITopicLazyLoader.cs @@ -7,14 +7,14 @@ namespace OnTopic.Repositories; /*============================================================================================================================== -| INTERFACE: TOPIC LOAD RESOLVER +| INTERFACE: TOPIC LAZY LOADER \-----------------------------------------------------------------------------------------------------------------------------*/ /// /// Provides a narrow seam through which a can populate one or more deferred payload on demand, without /// taking a dependency on the full . Instances are stamped onto topics by the repository as /// they are loaded or saved; topics created in memory carry no resolver. /// -public interface ITopicLoadResolver { +public interface ITopicLazyLoader { /*============================================================================================================================ | METHOD: ENSURE LOADED diff --git a/OnTopic/Repositories/LazyLoadingTopicRepository.cs b/OnTopic/Repositories/LazyLoadingTopicRepository.cs index d96565de..d101b38d 100644 --- a/OnTopic/Repositories/LazyLoadingTopicRepository.cs +++ b/OnTopic/Repositories/LazyLoadingTopicRepository.cs @@ -18,7 +18,7 @@ namespace OnTopic.Repositories; /// This sits between , which offers only event handling, and the two families of /// concrete base classes: , for implementations that persist /// directly to a data store, and , for implementations that wrap another . Both need to stamp topics with an and resolve deferred +/// "ITopicRepository"/>. Both need to stamp topics with an and resolve deferred /// associations, but neither should be coupled to the other's specific concerns (e.g., 's /// sealed Save(), Move(), and Delete() template methods, which /// must remain free to override for delegation). @@ -123,11 +123,11 @@ protected async Task ResolveDeferredAssociations(Topic topic, TopicPayload paylo \---------------------------------------------------------------------------------------------------------------------------*/ /// /// Stamps the supplied and its entire loaded graph with this repository as the , enabling each topic to populate deferred portions of itself on demand. + /// "ITopicLazyLoader"/>, enabling each topic to populate deferred portions of itself on demand. /// /// /// - /// Only stamps when the current repository implements . A passthrough decorator that is + /// Only stamps when the current repository implements . A passthrough decorator that is /// not itself a resolver leaves any existing inner stamp intact, rather than overwriting it. /// /// @@ -143,8 +143,8 @@ protected async Task ResolveDeferredAssociations(Topic topic, TopicPayload paylo /// The root of the topic graph to stamp. private void StampResolver(Topic? topic) { - // Skip if the TopicRepository is not an ITopicLoadResolver, or if the topic doesn't exist - if (this is not ITopicLoadResolver resolver || topic is null) { + // Skip if the TopicRepository is not an ITopicLazyLoader, or if the topic doesn't exist + if (this is not ITopicLazyLoader resolver || topic is null) { return; } @@ -168,7 +168,7 @@ private void StampResolver(Topic? topic) { \---------------------------------------------------------------------------------------------------------------------------*/ /// /// Walks a 's chain, stamping each with this repository as the , so an ascendant that was never individually loaded can still lazy-load its own deferred + /// cref="ITopicLazyLoader"/>, so an ascendant that was never individually loaded can still lazy-load its own deferred /// payload. /// /// @@ -191,8 +191,8 @@ private void StampResolver(Topic? topic) { /// private void StampAscendants(Topic? topic) { - // Skip if the current repository is not an ITopicLoadResolver - if (this is not ITopicLoadResolver resolver) { + // Skip if the current repository is not an ITopicLazyLoader + if (this is not ITopicLazyLoader resolver) { return; } diff --git a/OnTopic/Repositories/TopicPayload.cs b/OnTopic/Repositories/TopicPayload.cs index f05b2ba5..f95cb10f 100644 --- a/OnTopic/Repositories/TopicPayload.cs +++ b/OnTopic/Repositories/TopicPayload.cs @@ -11,12 +11,12 @@ namespace OnTopic.Repositories; \-----------------------------------------------------------------------------------------------------------------------------*/ /// /// Specifies which data ensure is loaded on a . Used as a parameter on 's -/// Load() overloads to control how much data is fetched in the first place, and on 's +/// Load() overloads to control how much data is fetched in the first place, and on 's /// Ensure() method to specify which previously deferred data to fill on demand. /// /// /// , , , , and -/// all have lazy-loading fill paths via . +/// all have lazy-loading fill paths via . /// /// The default value for all Load overloads is , so lazy loading /// is the default: Each boundary is fetched on demand via its autoloading accessor or an explicit EnsureLoaded call. diff --git a/OnTopic/Topic.cs b/OnTopic/Topic.cs index 5489dfdf..01d76f75 100644 --- a/OnTopic/Topic.cs +++ b/OnTopic/Topic.cs @@ -587,11 +587,11 @@ public DateTime LastModified { | PROPERTY: RESOLVER \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Provides an internal reference to the used to lazy load collections on request. This + /// Provides an internal reference to the used to lazy load collections on request. This /// is stamped by the with whichever /// most recently loaded or saved this topic. /// - internal ITopicLoadResolver? Resolver { get; set; } + internal ITopicLazyLoader? Resolver { get; set; } /*============================================================================================================================ | INTERFACE: TOPIC BACKING ACCESSOR From 9c884544b6031841702ce5ba1853616edd0c50a4 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 14 Jul 2026 02:08:36 -0700 Subject: [PATCH 160/337] Rename to `Resolve(r)` to `Load(er)` This rename `ResolveDeferredAssociations()` (b787626b) to `LoadDeferredAssociations()`, `Resolver` to `Loader` (a159b616, 819e3735), and `StampResolver()` to `StampLoader()` (cd215974) to align with the recent rename of `ITopicLoadResolver` to `ITopicLazyLoader` (a159b616). This also covers local variable for those objects to match. This is a refinement for #111. --- OnTopic.Data.Caching/CachedTopicRepository.cs | 6 +-- OnTopic.Data.Sql/SqlTopicRepository.cs | 2 +- .../StubLazyLoadingTopicRepository.cs | 8 ++-- OnTopic.Tests/TopicRepositoryBaseTest.cs | 8 ++-- OnTopic.Tests/TopicTest.cs | 2 +- .../LazyLoadingTopicRepository.cs | 42 +++++++++---------- OnTopic/Topic.cs | 22 +++++----- 7 files changed, 45 insertions(+), 45 deletions(-) diff --git a/OnTopic.Data.Caching/CachedTopicRepository.cs b/OnTopic.Data.Caching/CachedTopicRepository.cs index 13552d06..ac72a6c0 100644 --- a/OnTopic.Data.Caching/CachedTopicRepository.cs +++ b/OnTopic.Data.Caching/CachedTopicRepository.cs @@ -276,17 +276,17 @@ public virtual async Task EnsureLoaded(Topic topic, TopicPayload payload, Cancel | them, it would do so via its own, non-cache-aware Load(), producing a duplicate Topic instance for any target that's | already present in this cache. \-------------------------------------------------------------------------------------------------------------------------*/ - if (TopicRepository is ITopicLazyLoader resolver) { + if (TopicRepository is ITopicLazyLoader loader) { var innerPayload = payload & ~(TopicPayload.Relationships | TopicPayload.References); if (innerPayload is not TopicPayload.None) { - await resolver.EnsureLoaded(topic, innerPayload, cancellationToken).ConfigureAwait(false); + await loader.EnsureLoaded(topic, innerPayload, cancellationToken).ConfigureAwait(false); } } /*-------------------------------------------------------------------------------------------------------------------------- | Resolve any relationship and reference targets via the cache layer \-------------------------------------------------------------------------------------------------------------------------*/ - await ResolveDeferredAssociations(topic, payload, cancellationToken).ConfigureAwait(false); + await LoadDeferredAssociations(topic, payload, cancellationToken).ConfigureAwait(false); // Update flat index for any newly loaded children diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index 57322cbb..a046d8b6 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -404,7 +404,7 @@ public virtual async Task EnsureLoaded(Topic topic, TopicPayload payload, Cancel // initial Load() because their targets weren't part of that call's ascendant/descendant scope, and couldn't be found in the // referenceTopic, if provided. if (payload.HasFlag(TopicPayload.Relationships) || payload.HasFlag(TopicPayload.References)) { - await ResolveDeferredAssociations(topic, payload, cancellationToken).ConfigureAwait(false); + await LoadDeferredAssociations(topic, payload, cancellationToken).ConfigureAwait(false); } // Exit early if nothing else is pending so we don't open a database connection unnecessarily diff --git a/OnTopic.TestDoubles/LazyLoading/StubLazyLoadingTopicRepository.cs b/OnTopic.TestDoubles/LazyLoading/StubLazyLoadingTopicRepository.cs index b6dc4e52..4ae0e848 100644 --- a/OnTopic.TestDoubles/LazyLoading/StubLazyLoadingTopicRepository.cs +++ b/OnTopic.TestDoubles/LazyLoading/StubLazyLoadingTopicRepository.cs @@ -272,7 +272,7 @@ protected override Task SaveTopic([NotNull]Topic topic, DateTime version, bool p /// /// /// The on-demand fill: Unlike , this recursively resolves deferred - /// relationship and reference targets via the inherited ResolveDeferredAssociations, discarding whatever remains + /// relationship and reference targets via the inherited LoadDeferredAssociations, discarding whatever remains /// unresolved as stale, assuming either or . /// public virtual async Task EnsureLoaded(Topic topic, TopicPayload payload, CancellationToken cancellationToken = default) { @@ -305,7 +305,7 @@ public virtual async Task EnsureLoaded(Topic topic, TopicPayload payload, Cancel /// The requested flags. /// /// Whether unresolved relationships and references targets should be recursively loaded, via the inherited - /// ResolveDeferredAssociations. Set by 's on-demand + /// LoadDeferredAssociations. Set by 's on-demand /// fill; left by a plain Load(), which only connects targets already present in the graph, /// via . /// @@ -409,13 +409,13 @@ CancellationToken cancellationToken /*-------------------------------------------------------------------------------------------------------------------------- | Relationships and references: Resolve deferred targets >------------------------------------------------------------------------------------------------------------------------- - | Gated on what was actually requested, and delegates to the inherited ResolveDeferredAssociations, so this double + | Gated on what was actually requested, and delegates to the inherited LoadDeferredAssociations, so this double | utilizes that shared infrastructure. Resident targets were already connected above, regardless of this gate. \-------------------------------------------------------------------------------------------------------------------------*/ if (resolveDeferredTargets && associationPayload is not TopicPayload.None) { // Load any deferred relationships or references - await ResolveDeferredAssociations(topic, associationPayload, cancellationToken).ConfigureAwait(false); + await LoadDeferredAssociations(topic, associationPayload, cancellationToken).ConfigureAwait(false); // Mark the associations requested as fetched if (associationPayload.HasFlag(TopicPayload.Relationships)) { diff --git a/OnTopic.Tests/TopicRepositoryBaseTest.cs b/OnTopic.Tests/TopicRepositoryBaseTest.cs index 70f4ba35..e57d1552 100644 --- a/OnTopic.Tests/TopicRepositoryBaseTest.cs +++ b/OnTopic.Tests/TopicRepositoryBaseTest.cs @@ -1150,7 +1150,7 @@ public async Task Save_NewTopic_StampsResolver() { await _topicRepository.Save(topic); - Assert.NotNull(topic.Resolver); + Assert.NotNull(topic.Loader); } @@ -1227,7 +1227,7 @@ public async Task EnsureLoaded_MixedBoundaries_SkipsLoadedBoundaries() { /// /> via the 's fill. /// /// - /// On-demand fetching of non-resident relationship targets happens via ResolveDeferredAssociations() on LoadDeferredAssociations() on , which only invokes from its own /// EnsureLoaded()— does not resolve deferred targets itself. This test's stub fill /// simply marks the boundary without resolving the deferred target. @@ -1253,7 +1253,7 @@ public async Task EnsureLoaded_RelationshipsNotLoaded_MarksLoaded() { /// via the 's fill. /// /// - /// On-demand fetching of non-resident reference targets happens via ResolveDeferredAssociations() on LoadDeferredAssociations() on , which only invokes from its own /// EnsureLoaded()— does not resolve deferred targets itself. This test's stub fill /// simply marks the boundary without resolving the deferred target. @@ -1511,7 +1511,7 @@ public async Task Load_WithAscendants_StampsAscendantResolvers() { var ascendant = topic?.Parent?.Parent; Assert.NotNull(ascendant); - Assert.NotNull(ascendant?.Resolver); + Assert.NotNull(ascendant?.Loader); } diff --git a/OnTopic.Tests/TopicTest.cs b/OnTopic.Tests/TopicTest.cs index a419e9ee..4ffc0d61 100644 --- a/OnTopic.Tests/TopicTest.cs +++ b/OnTopic.Tests/TopicTest.cs @@ -565,7 +565,7 @@ public void EnsureLoaded_IsNew_DoesNotInvokeResolver() { | Establish tracking resolver \-------------------------------------------------------------------------------------------------------------------------*/ var tracker = new TrackingTopicLazyLoader(); - topic.Resolver = tracker; + topic.Loader = tracker; topic.Children.LoadState = LoadState.NotLoaded; /*-------------------------------------------------------------------------------------------------------------------------- diff --git a/OnTopic/Repositories/LazyLoadingTopicRepository.cs b/OnTopic/Repositories/LazyLoadingTopicRepository.cs index d101b38d..8a286da7 100644 --- a/OnTopic/Repositories/LazyLoadingTopicRepository.cs +++ b/OnTopic/Repositories/LazyLoadingTopicRepository.cs @@ -32,8 +32,8 @@ public abstract class LazyLoadingTopicRepository : ObservableTopicRepository { /// /// /// Stamps the from the , and any descendants attached to it, - /// via and before raising the event, so the - /// resolver gets stamped without the resolvers needing to be aware of it. + /// via and before raising the event, so the + /// loader gets stamped without the loaders needing to be aware of it. /// /// /// fires only for the requested topic, never individually for any descendants @@ -47,7 +47,7 @@ public abstract class LazyLoadingTopicRepository : ObservableTopicRepository { /// protected override void OnTopicLoaded(TopicLoadEventArgs args) { Contract.Requires(args, nameof(args)); - StampResolver(args.Topic); + StampLoader(args.Topic); StampAscendants(args.Topic.Parent); base.OnTopicLoaded(args); } @@ -57,17 +57,17 @@ protected override void OnTopicLoaded(TopicLoadEventArgs args) { \---------------------------------------------------------------------------------------------------------------------------*/ /// /// - /// Stamps the from the via + /// Stamps the from the via /// before raising the event for the same reason and via the same method as . /// protected override void OnTopicSaved(TopicSaveEventArgs args) { Contract.Requires(args, nameof(args)); - StampResolver(args.Topic); + StampLoader(args.Topic); base.OnTopicSaved(args); } /*============================================================================================================================ - | METHOD: RESOLVE DEFERRED ASSOCIATIONS + | METHOD: LOAD DEFERRED ASSOCIATIONS \---------------------------------------------------------------------------------------------------------------------------*/ /// /// Resolves any relationship and reference targets that were deferred when loading each through this repository's own @@ -84,7 +84,7 @@ protected override void OnTopicSaved(TopicSaveEventArgs args) { /// "TopicPayload.References"/> are acted upon. /// /// An optional token that can be used to cancel the operation. - protected async Task ResolveDeferredAssociations(Topic topic, TopicPayload payload, CancellationToken cancellationToken) { + protected async Task LoadDeferredAssociations(Topic topic, TopicPayload payload, CancellationToken cancellationToken) { // Validate input Contract.Requires(topic, nameof(topic)); @@ -119,7 +119,7 @@ protected async Task ResolveDeferredAssociations(Topic topic, TopicPayload paylo } /*============================================================================================================================ - | METHOD: STAMP RESOLVER + | METHOD: STAMP LOADER \---------------------------------------------------------------------------------------------------------------------------*/ /// /// Stamps the supplied and its entire loaded graph with this repository as the /// /// Only stamps when the current repository implements . A passthrough decorator that is - /// not itself a resolver leaves any existing inner stamp intact, rather than overwriting it. + /// not itself a loader leaves any existing inner stamp intact, rather than overwriting it. /// /// /// Recursion is gated on so that unloaded branches are not forced to load. @@ -141,15 +141,15 @@ protected async Task ResolveDeferredAssociations(Topic topic, TopicPayload paylo /// /// /// The root of the topic graph to stamp. - private void StampResolver(Topic? topic) { + private void StampLoader(Topic? topic) { // Skip if the TopicRepository is not an ITopicLazyLoader, or if the topic doesn't exist - if (this is not ITopicLazyLoader resolver || topic is null) { + if (this is not ITopicLazyLoader loader || topic is null) { return; } - // Stamp the resolver on the topic - topic.Resolver = resolver; + // Stamp the loader on the topic + topic.Loader = loader; // If the children aren't yet loaded, don't bother with them yet if (!topic.IsLoaded(TopicPayload.Children)) { @@ -158,7 +158,7 @@ private void StampResolver(Topic? topic) { // Stamp any children (this is recursive, obviously!) foreach (var child in topic.Children) { - StampResolver(child); + StampLoader(child); } } @@ -173,13 +173,13 @@ private void StampResolver(Topic? topic) { /// /// /// - /// Stops as soon as it reaches an ascendant already stamped by this exact resolver instance, on the assumption that its + /// Stops as soon as it reaches an ascendant already stamped by this exact loader instance, on the assumption that its /// own ascendants were already walked and stamped at that time. Comparing by instance, rather than merely checking for a - /// non-null , matters when this method runs as part of a decorated stack: An outer + /// non-null , matters when this method runs as part of a decorated stack: An outer /// decorator's pass must not stop early just because an inner repository already stamped the chain with itself. /// /// - /// In practice, this only short-circuits repeat calls against the same, undecorated resolver instance (e.g., a bare + /// In practice, this only short-circuits repeat calls against the same, undecorated loader instance (e.g., a bare /// loading many topics over its lifetime that share ascendant branches). When wrapped by a /// , the inner and outer passes stamp with different instances on every call, so /// neither ever finds a match from the other, and thus each pass walks the full chain to the root every time. That's @@ -192,13 +192,13 @@ private void StampResolver(Topic? topic) { private void StampAscendants(Topic? topic) { // Skip if the current repository is not an ITopicLazyLoader - if (this is not ITopicLazyLoader resolver) { + if (this is not ITopicLazyLoader loader) { return; } - // Walk and stamp each ascendant, stopping once this resolver has already stamped one - for (var ascendant = topic; ascendant is not null && ascendant.Resolver != resolver; ascendant = ascendant.Parent) { - ascendant.Resolver = resolver; + // Walk and stamp each ascendant, stopping once this loader has already stamped one + for (var ascendant = topic; ascendant is not null && ascendant.Loader != loader; ascendant = ascendant.Parent) { + ascendant.Loader = loader; } } diff --git a/OnTopic/Topic.cs b/OnTopic/Topic.cs index 01d76f75..6bb17408 100644 --- a/OnTopic/Topic.cs +++ b/OnTopic/Topic.cs @@ -19,7 +19,7 @@ namespace OnTopic; /// The Topic object is a simple container for a particular node in the topic hierarchy. It contains the metadata associated /// with the particular node, a list of children, etc. /// -public class Topic: ITrackDirtyKeys, ITopicBackingAccessor { +public class Topic: ITrackDirtyKeys, ITopicLazyLoadable { /*============================================================================================================================ | PRIVATE VARIABLES @@ -163,7 +163,7 @@ public Topic? Parent { public KeyedTopicCollection Children { get { if (_children.LoadState is LoadState.NotLoaded) { - EnsureLoaded(TopicPayload.Children).GetAwaiter().GetResult(); + ((ITopicLazyLoadable)this).EnsureLoaded(TopicPayload.Children).GetAwaiter().GetResult(); } return _children; } @@ -181,7 +181,7 @@ public KeyedTopicCollection Children { /// use in traversal and "gating" logic that should not trigger lazy-loading. /// /// One or more flags to test. - public bool IsLoaded(TopicPayload payload) { + bool ITopicLazyLoadable.IsLoaded(TopicPayload payload) { // Children if (payload.HasFlag(TopicPayload.Children) && _children.LoadState is not LoadState.Loaded) { @@ -278,7 +278,7 @@ public TopicPayload FilterPayload(TopicPayload payload) { /// /// Ensures each requested flag has been retrieved, while fetching and merging whichever of /// them are not yet , and silently skipping those that already are. Returns immediately if - /// the resolver is absent or the topic is new. + /// the loader is absent or the topic is new. /// /// /// Callers such as a mapping or navigation service can await this to prepopulate one or more payloads before accessing @@ -294,7 +294,7 @@ public Task EnsureLoaded(TopicPayload payload, CancellationToken cancellationTok /*-------------------------------------------------------------------------------------------------------------------------- | Skip for obvious reasons \-------------------------------------------------------------------------------------------------------------------------*/ - if (Resolver is null || IsNew) { + if (Loader is null || IsNew) { return Task.CompletedTask; } @@ -308,7 +308,7 @@ public Task EnsureLoaded(TopicPayload payload, CancellationToken cancellationTok } // Ensure the appropriate payload are loaded - return Resolver.EnsureLoaded(this, payload, cancellationToken); + return Loader.EnsureLoaded(this, payload, cancellationToken); } @@ -584,14 +584,14 @@ public DateTime LastModified { #region Lazy-Loading Infrastructure /*============================================================================================================================ - | PROPERTY: RESOLVER + | PROPERTY: LOADER \---------------------------------------------------------------------------------------------------------------------------*/ /// /// Provides an internal reference to the used to lazy load collections on request. This - /// is stamped by the with whichever + /// is stamped by the with whichever /// most recently loaded or saved this topic. /// - internal ITopicLazyLoader? Resolver { get; set; } + internal ITopicLazyLoader? Loader { get; set; } /*============================================================================================================================ | INTERFACE: TOPIC BACKING ACCESSOR @@ -935,7 +935,7 @@ public Topic? DerivedTopic { /// The current 's relationships. public TopicRelationshipMultiMap Relationships { get { - if (_relationships.LoadState is LoadState.NotLoaded && Resolver is not null) { + if (_relationships.LoadState is LoadState.NotLoaded && Loader is not null) { EnsureLoaded(TopicPayload.Relationships).GetAwaiter().GetResult(); } return _relationships; @@ -955,7 +955,7 @@ public TopicRelationshipMultiMap Relationships { /// The current 's references. public TopicReferenceCollection References { get { - if (_references.LoadState is LoadState.NotLoaded && Resolver is not null) { + if (_references.LoadState is LoadState.NotLoaded && Loader is not null) { EnsureLoaded(TopicPayload.References).GetAwaiter().GetResult(); } return _references; From 1007d6a70aca0309d9b40679e25c8e86fd2bb27d Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 14 Jul 2026 02:54:02 -0700 Subject: [PATCH 161/337] Introduce `ITopicLazyLoadable` This sits on top of `ITopicBackingAccessor` and formalizes the interface that the lazy-loading infrastructure (#111) expects on `Topic`. --- OnTopic/Repositories/ITopicLazyLoadable.cs | 90 ++++++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 OnTopic/Repositories/ITopicLazyLoadable.cs diff --git a/OnTopic/Repositories/ITopicLazyLoadable.cs b/OnTopic/Repositories/ITopicLazyLoadable.cs new file mode 100644 index 00000000..d2905269 --- /dev/null +++ b/OnTopic/Repositories/ITopicLazyLoadable.cs @@ -0,0 +1,90 @@ +/*============================================================================================================================== +| Author Ignia, LLC +| Client Ignia, LLC +| Project Topics Library +\=============================================================================================================================*/ +namespace OnTopic.Repositories; + +/*============================================================================================================================== +| INTERFACE: TOPIC LAZY LOADABLE +\-----------------------------------------------------------------------------------------------------------------------------*/ +/// +/// Provides the required members for the class to fully support , +/// including LoadState tracking and s reference to the that allows it to populate its +/// own deferred payload on demand. +/// +/// +/// is the sole implementer of this interface, and does so via explicit interface implementations; callers +/// must cast to to access these members. This keeps the infrastructure off 's public surface while still allowing repositories, the mapping layer, tests, and other infrastructure to reach it. +/// +public interface ITopicLazyLoadable : ITopicBackingAccessor { + + /*============================================================================================================================ + | METHOD: IS LOADED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Returns if every property flag in has already been fetched from the + /// underlying persistence store; if any one of them are . + /// + /// + /// Reads each collection's directly without touching any autoloading getter, making it safe to use + /// in traversal and "gating" logic that should not trigger lazy loading. + /// + /// One or more flags to test. + bool IsLoaded(TopicPayload payload); + + /*============================================================================================================================ + | METHOD: SET LOAD STATE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Sets the for each boundary flag in to . + /// + /// + /// Mirrors : Sets each collection's directly without touching + /// any autoloading getter. Callers are responsible for passing only payload whose transition is safe. + /// + /// One or more flags identifying the payload to update. + /// The to assign to each matched boundary's collection. + void SetLoadState(TopicPayload payload, LoadState state); + + /*============================================================================================================================ + | METHOD: FILTER PAYLOAD + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Returns with any already- flags cleared, so callers skip + /// redundant round trips. + /// + /// The requested flags to filter. + TopicPayload FilterPayload(TopicPayload payload); + + /*============================================================================================================================ + | METHODS: ENSURE LOADED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Ensures each requested flag has been retrieved, while fetching and merging whichever of them + /// are not yet , and skipping those that already are. Returns immediately if the is absent. + /// + /// + /// Callers such as a mapping or navigation service can await this to prepopulate one or more payloads before accessing + /// them, thus avoiding a synchronous block on a sparse topic. The autoloading property getters (e.g., ) call this synchronously via GetAwaiter().GetResult() as an accepted sync-over-async boundary. + /// + /// + /// One or more flags identifying the payload that should be ensured to be loaded. + /// + /// An optional token that can be used to cancel the operation. + Task EnsureLoaded(TopicPayload payload, CancellationToken cancellationToken = default); + + /*============================================================================================================================ + | PROPERTY: LOADER + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Provides a reference to the used to lazy load collections on request. This is stamped + /// by with whichever most recently + /// loaded or saved this topic. + /// + ITopicLazyLoader? Loader { get; set; } + +} //Interface \ No newline at end of file From 248411eac343652383300566f9efa1f1df1d870a Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 14 Jul 2026 02:57:04 -0700 Subject: [PATCH 162/337] Make `ITopicLazyLoadable` an explicit interface This modifies `Topic` to use explicit interface implementations of the newly introduced `ITopicLazyLoadable` (1007d6a7) and, thus, requires those members to be engaged as `ITopicLazyLoadable` to access the lazy-loading infrastructure (#111), therefore hiding them from developers adopting OnTopic, but not those who are extending the infrastructure. This is a bit noisy because it requires every call site to these members to be cast to `ITopicLazyLoadable` in order to access the members. This also updated the `EnsureLoaded_IsNew_DoesNotInvokeResolver()` test to the `IsNew_NewTopic_HasNullLoader()`, which better captures the behavior. --- OnTopic.Data.Caching/CachedTopicRepository.cs | 2 +- OnTopic.Data.Sql/SqlDataReaderExtensions.cs | 2 +- OnTopic.Data.Sql/SqlTopicRepository.cs | 4 +- .../StubLazyLoadingTopicRepository.cs | 10 +-- OnTopic.TestDoubles/StubTopicRepository.cs | 2 +- OnTopic.Tests/SqlTopicRepositoryTest.cs | 28 +++---- OnTopic.Tests/TopicRepositoryBaseTest.cs | 82 +++++++++---------- OnTopic.Tests/TopicTest.cs | 42 +++------- OnTopic/Attributes/AttributeCollection.cs | 2 +- OnTopic/Mapping/TopicMappingService.cs | 3 +- OnTopic/Querying/TopicExtensions.cs | 4 +- .../LazyLoadingTopicRepository.cs | 18 ++-- OnTopic/Repositories/TopicRepository.cs | 2 +- OnTopic/Topic.cs | 44 +++++----- 14 files changed, 112 insertions(+), 133 deletions(-) diff --git a/OnTopic.Data.Caching/CachedTopicRepository.cs b/OnTopic.Data.Caching/CachedTopicRepository.cs index ac72a6c0..27000ab9 100644 --- a/OnTopic.Data.Caching/CachedTopicRepository.cs +++ b/OnTopic.Data.Caching/CachedTopicRepository.cs @@ -261,7 +261,7 @@ public virtual async Task EnsureLoaded(Topic topic, TopicPayload payload, Cancel /*-------------------------------------------------------------------------------------------------------------------------- | Filter to pending (i.e., not yet Loaded) payload \-------------------------------------------------------------------------------------------------------------------------*/ - payload = topic.FilterPayload(payload); + payload = ((ITopicLazyLoadable)topic).FilterPayload(payload); if (payload is TopicPayload.None) { return; diff --git a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs index e7b68437..26ba8c23 100644 --- a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs +++ b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs @@ -293,7 +293,7 @@ CancellationToken cancellationToken } // Mark confirmed children payload as Loaded - parent.SetLoadState(TopicPayload.Children, LoadState.Loaded); + ((ITopicLazyLoadable)parent).SetLoadState(TopicPayload.Children, LoadState.Loaded); } diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index a046d8b6..8426a7ff 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -391,7 +391,7 @@ public virtual async Task EnsureLoaded(Topic topic, TopicPayload payload, Cancel /*-------------------------------------------------------------------------------------------------------------------------- | Filter to pending (not yet Loaded) payload \-------------------------------------------------------------------------------------------------------------------------*/ - payload = topic.FilterPayload(payload); + payload = ((ITopicLazyLoadable)topic).FilterPayload(payload); if (payload is TopicPayload.None) { return; @@ -513,7 +513,7 @@ public virtual async Task EnsureLoaded(Topic topic, TopicPayload payload, Cancel | are computed from Deferred.Count and require no explicit assignment here. History is set directly by SetVersionHistory() | as rows are read, since every persisted topic has at least one version. Only Extended Attributes needs to be set here. \-------------------------------------------------------------------------------------------------------------------------*/ - topic.SetLoadState(payload & TopicPayload.ExtendedAttributes, LoadState.Loaded); + ((ITopicLazyLoadable)topic).SetLoadState(payload & TopicPayload.ExtendedAttributes, LoadState.Loaded); } diff --git a/OnTopic.TestDoubles/LazyLoading/StubLazyLoadingTopicRepository.cs b/OnTopic.TestDoubles/LazyLoading/StubLazyLoadingTopicRepository.cs index 4ae0e848..02cde23a 100644 --- a/OnTopic.TestDoubles/LazyLoading/StubLazyLoadingTopicRepository.cs +++ b/OnTopic.TestDoubles/LazyLoading/StubLazyLoadingTopicRepository.cs @@ -336,7 +336,7 @@ CancellationToken cancellationToken /*-------------------------------------------------------------------------------------------------------------------------- | Filter out any already loaded payloads \-------------------------------------------------------------------------------------------------------------------------*/ - payload = topic.FilterPayload(payload); + payload = ((ITopicLazyLoadable)topic).FilterPayload(payload); if (payload is TopicPayload.None) { return; @@ -386,7 +386,7 @@ CancellationToken cancellationToken // Mark the children as fetched and loaded RecordFetch(topic.Id, TopicPayload.Children); - topic.SetLoadState(TopicPayload.Children, LoadState.Loaded); + ((ITopicLazyLoadable)topic).SetLoadState(TopicPayload.Children, LoadState.Loaded); } @@ -402,7 +402,7 @@ CancellationToken cancellationToken // Mark the extended attributes as fetched and loaded RecordFetch(topic.Id, TopicPayload.ExtendedAttributes); - topic.SetLoadState(TopicPayload.ExtendedAttributes, LoadState.Loaded); + ((ITopicLazyLoadable)topic).SetLoadState(TopicPayload.ExtendedAttributes, LoadState.Loaded); } @@ -506,10 +506,10 @@ private Topic BuildTopic(TopicRecord record, Topic parent) { } // Set extended attributes - topic.SetLoadState(TopicPayload.ExtendedAttributes, LoadState.NotLoaded); + ((ITopicLazyLoadable)topic).SetLoadState(TopicPayload.ExtendedAttributes, LoadState.NotLoaded); // Set children - topic.SetLoadState(TopicPayload.Children, LoadState.NotLoaded); + ((ITopicLazyLoadable)topic).SetLoadState(TopicPayload.Children, LoadState.NotLoaded); // Add relationships to Deferred foreach (var (key, targetId) in record.Relationships) { diff --git a/OnTopic.TestDoubles/StubTopicRepository.cs b/OnTopic.TestDoubles/StubTopicRepository.cs index b54046e9..90ac0c36 100644 --- a/OnTopic.TestDoubles/StubTopicRepository.cs +++ b/OnTopic.TestDoubles/StubTopicRepository.cs @@ -199,7 +199,7 @@ public virtual Task EnsureLoaded(Topic topic, TopicPayload payload, Cancellation | Mark payload as loaded; stubs have all relationships and references pre-built in memory, so all targets are resident | and marking Loaded is always safe. Children is already populated in the stubs and needs no action. \-------------------------------------------------------------------------------------------------------------------------*/ - topic.SetLoadState(payload, LoadState.Loaded); + ((ITopicLazyLoadable)topic).SetLoadState(payload, LoadState.Loaded); // Relationships and References are computed from Deferred.Count; clear any test-seeded deferred entries to express Loaded var rawTopic = (ITopicBackingAccessor)topic; diff --git a/OnTopic.Tests/SqlTopicRepositoryTest.cs b/OnTopic.Tests/SqlTopicRepositoryTest.cs index 31fc84a5..ddfbed18 100644 --- a/OnTopic.Tests/SqlTopicRepositoryTest.cs +++ b/OnTopic.Tests/SqlTopicRepositoryTest.cs @@ -162,7 +162,7 @@ public async Task LoadTopicGraph_WithRelationship_ReturnsRelationship() { Assert.NotNull(topic); Assert.Equal(1, topic.Id); Assert.Equal(2, topic.Relationships.GetValues("Test").FirstOrDefault()?.Id); - Assert.True(topic.IsLoaded(TopicPayload.Relationships)); + Assert.True(((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.Relationships)); } @@ -190,7 +190,7 @@ public async Task LoadTopicGraph_WithMissingRelationship_NotFullyLoaded() { Assert.NotNull(topic); Assert.Equal(1, topic.Id); Assert.Empty(topic.Relationships); - Assert.False(topic.IsLoaded(TopicPayload.Relationships)); + Assert.False(((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.Relationships)); } @@ -249,7 +249,7 @@ public async Task LoadTopicGraph_WithExternalReference_ReturnsReference() { Assert.NotNull(topic); Assert.Equal(1, topic.Id); Assert.Equal(2, topic.References.GetValue("Test")?.Id); - Assert.True(topic.IsLoaded(TopicPayload.References)); + Assert.True(((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.References)); Assert.False(topic.References.IsDirty()); } @@ -309,7 +309,7 @@ public async Task LoadTopicGraph_WithMissingReference_NotFullyLoaded() { Assert.NotNull(topic); Assert.Equal(1, topic.Id); Assert.Empty(topic.References); - Assert.False(topic.IsLoaded(TopicPayload.References)); + Assert.False(((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.References)); } @@ -370,7 +370,7 @@ public async Task LoadTopicGraph_IndexedOnlyWithRelationship_ReturnsLoaded() { var topic = await tableReader.LoadTopicGraph(cancellationToken: CancellationToken); Assert.NotNull(topic); - Assert.True(topic.IsLoaded(TopicPayload.Relationships)); + Assert.True(((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.Relationships)); } @@ -401,7 +401,7 @@ public async Task LoadTopicGraph_IndexedOnlyWithMissingRelationship_ReturnsNotLo var topic = await tableReader.LoadTopicGraph(cancellationToken: CancellationToken); Assert.NotNull(topic); - Assert.False(topic.IsLoaded(TopicPayload.Relationships)); + Assert.False(((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.Relationships)); } @@ -428,7 +428,7 @@ public async Task LoadTopicGraph_IndexedOnlyWithReference_ReturnsLoaded() { var topic = await tableReader.LoadTopicGraph(cancellationToken: CancellationToken); Assert.NotNull(topic); - Assert.True(topic.IsLoaded(TopicPayload.References)); + Assert.True(((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.References)); } @@ -455,7 +455,7 @@ public async Task LoadTopicGraph_IndexedOnlyWithMissingReference_ReturnsNotLoade var topic = await tableReader.LoadTopicGraph(cancellationToken: CancellationToken); Assert.NotNull(topic); - Assert.False(topic.IsLoaded(TopicPayload.References)); + Assert.False(((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.References)); } @@ -482,7 +482,7 @@ public async Task LoadTopicGraph_WithMissingRelationship_SetsNotLoaded() { var topic = await tableReader.LoadTopicGraph(cancellationToken: CancellationToken); Assert.NotNull(topic); - Assert.False(topic.IsLoaded(TopicPayload.Relationships)); + Assert.False(((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.Relationships)); } @@ -509,7 +509,7 @@ public async Task LoadTopicGraph_WithMissingReference_SetsNotLoaded() { var topic = await tableReader.LoadTopicGraph(cancellationToken: CancellationToken); Assert.NotNull(topic); - Assert.False(topic.IsLoaded(TopicPayload.References)); + Assert.False(((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.References)); } @@ -533,7 +533,7 @@ public async Task LoadTopicGraph_WithHistoryDeferred_ReturnsNotLoaded() { var topic = await tableReader.LoadTopicGraph(cancellationToken: CancellationToken); Assert.NotNull(topic); - Assert.False(topic.IsLoaded(TopicPayload.VersionHistory)); + Assert.False(((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.VersionHistory)); } @@ -585,7 +585,7 @@ public async Task LoadTopicGraph_WithExtendedDeferredAndBlob_ReturnsNotLoaded() var topic = await tableReader.LoadTopicGraph(cancellationToken: CancellationToken); Assert.NotNull(topic); - Assert.False(topic.IsLoaded(TopicPayload.ExtendedAttributes)); + Assert.False(((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.ExtendedAttributes)); } @@ -656,7 +656,7 @@ public async Task LoadTopicGraph_WithHasChildrenFalse_ReturnsChildrenLoaded() { var topic = await tableReader.LoadTopicGraph(1, cancellationToken: CancellationToken); - Assert.True(topic?.IsLoaded(TopicPayload.Children)); + Assert.True(((ITopicLazyLoadable)topic)?.IsLoaded(TopicPayload.Children)); } @@ -680,7 +680,7 @@ public async Task LoadTopicGraph_WithHasChildrenAndLoadedChildren_ReturnsChildre var topic = await tableReader.LoadTopicGraph(1, cancellationToken: CancellationToken); - Assert.True(topic?.IsLoaded(TopicPayload.Children)); + Assert.True(((ITopicLazyLoadable)topic)?.IsLoaded(TopicPayload.Children)); } diff --git a/OnTopic.Tests/TopicRepositoryBaseTest.cs b/OnTopic.Tests/TopicRepositoryBaseTest.cs index e57d1552..98a2e08b 100644 --- a/OnTopic.Tests/TopicRepositoryBaseTest.cs +++ b/OnTopic.Tests/TopicRepositoryBaseTest.cs @@ -1150,7 +1150,7 @@ public async Task Save_NewTopic_StampsResolver() { await _topicRepository.Save(topic); - Assert.NotNull(topic.Loader); + Assert.NotNull(((ITopicLazyLoadable)topic).Loader); } @@ -1160,7 +1160,7 @@ public async Task Save_NewTopic_StampsResolver() { /// /// Creates a parent topic with a child, marks the parent's as , then saves recursively. Verifies that the child is not saved; the recursive-save loop is gated on , so a not-loaded children collection prevents descent. + /// "ITopicLazyLoadable.IsLoaded(TopicPayload)"/>, so a not-loaded children collection prevents descent. /// [Fact] public async Task Save_NotLoadedChildren_SkipsRecursiveDescent() { @@ -1181,8 +1181,8 @@ public async Task Save_NotLoadedChildren_SkipsRecursiveDescent() { \---------------------------------------------------------------------------------------------------------------------------*/ /// /// Loads a whose extended-attribute boundary has been manually set to - /// and confirms that promotes the boundary to via the 's fill. + /// and confirms that promotes the boundary + /// to via the 's fill. /// [Fact] public async Task EnsureLoaded_ExtendedAttributesNotLoaded_MarksLoaded() { @@ -1190,9 +1190,9 @@ public async Task EnsureLoaded_ExtendedAttributesNotLoaded_MarksLoaded() { var topic = await _topicRepository.Load(11111); topic!.Attributes.LoadState = LoadState.NotLoaded; - topic.EnsureLoaded(TopicPayload.ExtendedAttributes); + ((ITopicLazyLoadable)topic).EnsureLoaded(TopicPayload.ExtendedAttributes); - Assert.True(topic.IsLoaded(TopicPayload.ExtendedAttributes)); + Assert.True(((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.ExtendedAttributes)); } @@ -1200,9 +1200,9 @@ public async Task EnsureLoaded_ExtendedAttributesNotLoaded_MarksLoaded() { | TEST: ENSURE LOADED: MIXED BOUNDARIES: SKIPS LOADED BOUNDARIES \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Calls with a mixed set of flags, including one already set to and one , and confirms that only the pending boundary is - /// forwarded to the resolver, leaving the already-loaded boundary unchanged. + /// Calls with a mixed set of flags, + /// including one already set to and one , and confirms that + /// only the pending boundary is forwarded to the resolver, leaving the already-loaded boundary unchanged. /// [Fact] public async Task EnsureLoaded_MixedBoundaries_SkipsLoadedBoundaries() { @@ -1210,11 +1210,11 @@ public async Task EnsureLoaded_MixedBoundaries_SkipsLoadedBoundaries() { var topic = await _topicRepository.Load(11111); topic!.Attributes.LoadState = LoadState.NotLoaded; - Assert.True(topic.IsLoaded(TopicPayload.Children)); - topic.EnsureLoaded(TopicPayload.Children | TopicPayload.ExtendedAttributes); + Assert.True(((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.Children)); + ((ITopicLazyLoadable)topic).EnsureLoaded(TopicPayload.Children | TopicPayload.ExtendedAttributes); - Assert.True(topic.IsLoaded(TopicPayload.ExtendedAttributes)); - Assert.True(topic.IsLoaded(TopicPayload.Children)); + Assert.True(((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.ExtendedAttributes)); + Assert.True(((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.Children)); } @@ -1223,8 +1223,8 @@ public async Task EnsureLoaded_MixedBoundaries_SkipsLoadedBoundaries() { \---------------------------------------------------------------------------------------------------------------------------*/ /// /// Loads a whose relationship boundary has been manually set to - /// and confirms that promotes the boundary to via the 's fill. + /// and confirms that promotes the boundary + /// to via the 's fill. /// /// /// On-demand fetching of non-resident relationship targets happens via LoadDeferredAssociations() on /// Loads a whose reference boundary has been manually set to and - /// confirms that promotes the boundary to - /// via the 's fill. + /// confirms that promotes the boundary to + /// via the 's fill. /// /// /// On-demand fetching of non-resident reference targets happens via LoadDeferredAssociations() on /// Loads a whose has been manually set to and confirms that promotes the boundary to via the 's fill. + /// /> and confirms that promotes the + /// boundary to via the 's fill. /// [Fact] public async Task EnsureLoaded_ChildrenNotLoaded_MarksLoaded() { var topic = await _topicRepository.Load(11111); - topic!.SetLoadState(TopicPayload.Children, LoadState.NotLoaded); - topic.EnsureLoaded(TopicPayload.Children); + ((ITopicLazyLoadable)topic!).SetLoadState(TopicPayload.Children, LoadState.NotLoaded); + ((ITopicLazyLoadable)topic).EnsureLoaded(TopicPayload.Children); - Assert.True(topic.IsLoaded(TopicPayload.Children)); + Assert.True(((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.Children)); } @@ -1414,8 +1414,8 @@ public async Task EnsureLoaded_ChildrenNotLoaded_MarksLoaded() { | TEST: MOVE: TOPIC MOVED EVENT: IS RAISED \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Creates a and then immediately moves it. Ensures that the event is raised. + /// Creates a and then immediately moves it. Ensures that the + /// event is raised. /// [Fact] public async Task Move_TopicMovedEvent_IsRaised() { @@ -1438,8 +1438,8 @@ public async Task Move_TopicMovedEvent_IsRaised() { | TEST: ENSURE LOADED: WITH MISSING RELATIONSHIP TARGET: RESOLVES AND CONNECTS \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Calls on a topic whose Relationships.LoadState is NotLoaded, - /// confirming that the resolver re-queries for the topic's relationships, loads any missing targets, and connects the + /// Calls on a topic whose Relationships.LoadState is NotLoaded + /// , confirming that the resolver re-queries for the topic's relationships, loads any missing targets, and connects the /// edges. /// /// @@ -1511,7 +1511,7 @@ public async Task Load_WithAscendants_StampsAscendantResolvers() { var ascendant = topic?.Parent?.Parent; Assert.NotNull(ascendant); - Assert.NotNull(ascendant?.Loader); + Assert.NotNull((ascendant as ITopicLazyLoadable)?.Loader); } diff --git a/OnTopic.Tests/TopicTest.cs b/OnTopic.Tests/TopicTest.cs index 4ffc0d61..e7be03a5 100644 --- a/OnTopic.Tests/TopicTest.cs +++ b/OnTopic.Tests/TopicTest.cs @@ -6,7 +6,6 @@ using OnTopic.Collections; using OnTopic.Metadata; using OnTopic.Repositories; -using OnTopic.Tests.TestDoubles; using Xunit; namespace OnTopic.Tests; @@ -507,7 +506,6 @@ public void MarkClean_IncludeCollections_ResetsIsDirty() { } - /*============================================================================================================================ | MARK CLEAN: NEW TOPIC: REMAINS DIRTY \---------------------------------------------------------------------------------------------------------------------------*/ @@ -533,47 +531,31 @@ public void MarkClean_NewTopic_RemainsDirty() { | TEST: ENSURE LOADED: NULL RESOLVER: DOES NOT THROW \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Calls on an in-memory topic with no resolver and confirms it completes - /// without throwing. + /// Calls on an in-memory topic with no + /// loader and confirms it completes without throwing. /// [Fact] public void EnsureLoaded_NullResolver_DoesNotThrow() { var topic = new Topic("Topic", "Page"); - topic.EnsureLoaded(TopicPayload.All); + ((ITopicLazyLoadable)topic).EnsureLoaded(TopicPayload.All); } /*============================================================================================================================ - | TEST: ENSURE LOADED: IS NEW: DOES NOT INVOKE RESOLVER + | TEST: IS NEW: NEW TOPIC: HAS NULL LOADER \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Calls on a new topic (no ) that has a resolver - /// stamped on it and confirms the resolver is not invoked. + /// Confirms that a newly constructed, unsaved carries a null . /// /// - /// A new topic may carry a resolver if it was created as a child of a loaded node; it must not trigger a fill until it has - /// been persisted and has a stable . + /// Ensures that only stamps + /// once a topic has been loaded or saved (and thus has a stable ), so an in-memory, unsaved topic can + /// never carry one. /// [Fact] - public void EnsureLoaded_IsNew_DoesNotInvokeResolver() { - - /*-------------------------------------------------------------------------------------------------------------------------- - | Establish variables - \-------------------------------------------------------------------------------------------------------------------------*/ - var topic = new Topic("Topic", "Page"); // Id = -1 → IsNew = true - - /*-------------------------------------------------------------------------------------------------------------------------- - | Establish tracking resolver - \-------------------------------------------------------------------------------------------------------------------------*/ - var tracker = new TrackingTopicLazyLoader(); - topic.Loader = tracker; - topic.Children.LoadState = LoadState.NotLoaded; - - /*-------------------------------------------------------------------------------------------------------------------------- - | Verify resolver is not called - \-------------------------------------------------------------------------------------------------------------------------*/ - topic.EnsureLoaded(TopicPayload.Children); - Assert.False(tracker.WasCalled); - + public void IsNew_NewTopic_HasNullLoader() { + var topic = new Topic("Topic", "Page"); // ID = -1, IsNew = true + Assert.True(topic.IsNew); + Assert.Null(((ITopicLazyLoadable)topic).Loader); } } //Class \ No newline at end of file diff --git a/OnTopic/Attributes/AttributeCollection.cs b/OnTopic/Attributes/AttributeCollection.cs index 6c96e536..0db0848b 100644 --- a/OnTopic/Attributes/AttributeCollection.cs +++ b/OnTopic/Attributes/AttributeCollection.cs @@ -119,7 +119,7 @@ public bool IsDirty(bool excludeLastModified) [return: NotNullIfNotNull(nameof(defaultValue))] internal override string? GetValue(string key, string? defaultValue, bool inheritFromParent, int maxHops) { if (LoadState is LoadState.NotLoaded && !Contains(key)) { - AssociatedTopic.EnsureLoaded(TopicPayload.ExtendedAttributes); + ((ITopicLazyLoadable)AssociatedTopic).EnsureLoaded(TopicPayload.ExtendedAttributes); } return base.GetValue(key, defaultValue, inheritFromParent, maxHops); } diff --git a/OnTopic/Mapping/TopicMappingService.cs b/OnTopic/Mapping/TopicMappingService.cs index 6a05501a..a9cab4ce 100644 --- a/OnTopic/Mapping/TopicMappingService.cs +++ b/OnTopic/Mapping/TopicMappingService.cs @@ -803,7 +803,8 @@ private async Task> GetSourceCollectionAsync( /*-------------------------------------------------------------------------------------------------------------------------- | Warm lazy-loaded payload before probing collections \-------------------------------------------------------------------------------------------------------------------------*/ - await source.EnsureLoaded(AssociationMap.PayloadMappings[configuration.CollectionType]).ConfigureAwait(false); + await ((ITopicLazyLoadable)source).EnsureLoaded(AssociationMap.PayloadMappings[configuration.CollectionType]).ConfigureAwait(false); + var listSource = (IList)[]; var collectionKey = configuration.CollectionKey; var collectionType = configuration.CollectionType; diff --git a/OnTopic/Querying/TopicExtensions.cs b/OnTopic/Querying/TopicExtensions.cs index bc068182..3e25859e 100644 --- a/OnTopic/Querying/TopicExtensions.cs +++ b/OnTopic/Querying/TopicExtensions.cs @@ -56,7 +56,7 @@ public static class TopicExtensions { /*-------------------------------------------------------------------------------------------------------------------------- | Recurse over children \-------------------------------------------------------------------------------------------------------------------------*/ - if (topic.IsLoaded(TopicPayload.Children)) { + if (((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.Children)) { foreach (var child in topic.Children) { var nestedResult = child.FindFirst(predicate); if (nestedResult is not null) { @@ -155,7 +155,7 @@ public static ReadOnlyTopicCollection FindAll(this Topic topic, Func /// - /// Recursion is gated on so that unloaded branches are not forced to load. - /// Since is an autoloading getter, recursing into it unconditionally would trigger a load - /// for every branch just to stamp it; the gate keeps this confined to what's already - /// present. + /// Recursion is gated on so that unloaded branches are not forced + /// to load. Since is an autoloading getter, recursing into it unconditionally would trigger + /// a load for every branch just to stamp it; the gate keeps this confined to what's + /// already present. /// /// /// Call this method once on the root of a recently loaded or saved graph; it stamps every present topic in one pass. @@ -149,10 +149,10 @@ private void StampLoader(Topic? topic) { } // Stamp the loader on the topic - topic.Loader = loader; + ((ITopicLazyLoadable)topic).Loader = loader; // If the children aren't yet loaded, don't bother with them yet - if (!topic.IsLoaded(TopicPayload.Children)) { + if (!((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.Children)) { return; } @@ -175,7 +175,7 @@ private void StampLoader(Topic? topic) { /// /// Stops as soon as it reaches an ascendant already stamped by this exact loader instance, on the assumption that its /// own ascendants were already walked and stamped at that time. Comparing by instance, rather than merely checking for a - /// non-null , matters when this method runs as part of a decorated stack: An outer + /// non-null , matters when this method runs as part of a decorated stack: An outer /// decorator's pass must not stop early just because an inner repository already stamped the chain with itself. /// /// @@ -197,8 +197,8 @@ private void StampAscendants(Topic? topic) { } // Walk and stamp each ascendant, stopping once this loader has already stamped one - for (var ascendant = topic; ascendant is not null && ascendant.Loader != loader; ascendant = ascendant.Parent) { - ascendant.Loader = loader; + for (var ascendant = topic; ascendant is not null && ((ITopicLazyLoadable)ascendant).Loader != loader; ascendant = ascendant.Parent) { + ((ITopicLazyLoadable)ascendant).Loader = loader; } } diff --git a/OnTopic/Repositories/TopicRepository.cs b/OnTopic/Repositories/TopicRepository.cs index 2b028d0f..6dc1bff6 100644 --- a/OnTopic/Repositories/TopicRepository.cs +++ b/OnTopic/Repositories/TopicRepository.cs @@ -448,7 +448,7 @@ _contentTypeDescriptors is not null && /*-------------------------------------------------------------------------------------------------------------------------- | Recurse over children \-------------------------------------------------------------------------------------------------------------------------*/ - if (isRecursive && topic.IsLoaded(TopicPayload.Children)) { + if (isRecursive && ((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.Children)) { foreach (var childTopic in topic.Children.ToList()) { await Save(childTopic, isRecursive, unresolvedTopics, version).ConfigureAwait(false); } diff --git a/OnTopic/Topic.cs b/OnTopic/Topic.cs index 6bb17408..2ec63dce 100644 --- a/OnTopic/Topic.cs +++ b/OnTopic/Topic.cs @@ -220,15 +220,15 @@ bool ITopicLazyLoadable.IsLoaded(TopicPayload payload) { /// Sets the for each boundary flag in to . /// /// - /// Mirrors : Sets each collection's directly without touching - /// any autoloading getter. Callers are responsible for passing only payload whose transition is safe; for example, and should only be promoted to after confirming all targets are available in the graph, since - /// permits DeleteUnmatched on save. + /// Mirrors : Sets each collection's directly + /// without touching any autoloading getter. Callers are responsible for passing only payload whose transition is safe; for + /// example, and should only be promoted to + /// after confirming all targets are available in the graph, since permits DeleteUnmatched on save. /// /// One or more flags identifying the payload to update. /// The to assign to each matched boundary's collection. - public void SetLoadState(TopicPayload payload, LoadState state) { + void ITopicLazyLoadable.SetLoadState(TopicPayload payload, LoadState state) { // Children if (payload.HasFlag(TopicPayload.Children)) { @@ -255,14 +255,14 @@ public void SetLoadState(TopicPayload payload, LoadState state) { /// redundant round-trips. /// /// The requested flags to filter. - public TopicPayload FilterPayload(TopicPayload payload) { + TopicPayload ITopicLazyLoadable.FilterPayload(TopicPayload payload) { // Strip already-loaded payload foreach (var flag in Enum.GetValues()) { if (flag is TopicPayload.None or TopicPayload.All) { continue; } - if (IsLoaded(flag)) { + if (((ITopicLazyLoadable)this).IsLoaded(flag)) { payload &= ~flag; } } @@ -278,7 +278,7 @@ public TopicPayload FilterPayload(TopicPayload payload) { /// /// Ensures each requested flag has been retrieved, while fetching and merging whichever of /// them are not yet , and silently skipping those that already are. Returns immediately if - /// the loader is absent or the topic is new. + /// the loader is absent. /// /// /// Callers such as a mapping or navigation service can await this to prepopulate one or more payloads before accessing @@ -289,26 +289,26 @@ public TopicPayload FilterPayload(TopicPayload payload) { /// One or more flags identifying the payload that should be ensured to be loaded. /// /// An optional token that can be used to cancel the operation. - public Task EnsureLoaded(TopicPayload payload, CancellationToken cancellationToken = default) { + Task ITopicLazyLoadable.EnsureLoaded(TopicPayload payload, CancellationToken cancellationToken) { /*-------------------------------------------------------------------------------------------------------------------------- | Skip for obvious reasons \-------------------------------------------------------------------------------------------------------------------------*/ - if (Loader is null || IsNew) { + if (((ITopicLazyLoadable)this).Loader is not { } loader) { return Task.CompletedTask; } /*-------------------------------------------------------------------------------------------------------------------------- | Filter to payload that are not yet loaded \-------------------------------------------------------------------------------------------------------------------------*/ - payload = FilterPayload(payload); + payload = ((ITopicLazyLoadable)this).FilterPayload(payload); if (payload is TopicPayload.None) { return Task.CompletedTask; } // Ensure the appropriate payload are loaded - return Loader.EnsureLoaded(this, payload, cancellationToken); + return loader.EnsureLoaded(this, payload, cancellationToken); } @@ -586,12 +586,8 @@ public DateTime LastModified { /*============================================================================================================================ | PROPERTY: LOADER \---------------------------------------------------------------------------------------------------------------------------*/ - /// - /// Provides an internal reference to the used to lazy load collections on request. This - /// is stamped by the with whichever - /// most recently loaded or saved this topic. - /// - internal ITopicLazyLoader? Loader { get; set; } + /// + ITopicLazyLoader? ITopicLazyLoadable.Loader { get; set; } /*============================================================================================================================ | INTERFACE: TOPIC BACKING ACCESSOR @@ -935,8 +931,8 @@ public Topic? DerivedTopic { /// The current 's relationships. public TopicRelationshipMultiMap Relationships { get { - if (_relationships.LoadState is LoadState.NotLoaded && Loader is not null) { - EnsureLoaded(TopicPayload.Relationships).GetAwaiter().GetResult(); + if (_relationships.LoadState is LoadState.NotLoaded) { + ((ITopicLazyLoadable)this).EnsureLoaded(TopicPayload.Relationships).GetAwaiter().GetResult(); } return _relationships; } @@ -955,8 +951,8 @@ public TopicRelationshipMultiMap Relationships { /// The current 's references. public TopicReferenceCollection References { get { - if (_references.LoadState is LoadState.NotLoaded && Loader is not null) { - EnsureLoaded(TopicPayload.References).GetAwaiter().GetResult(); + if (_references.LoadState is LoadState.NotLoaded) { + ((ITopicLazyLoadable)this).EnsureLoaded(TopicPayload.References).GetAwaiter().GetResult(); } return _references; } @@ -991,7 +987,7 @@ public TopicReferenceCollection References { public VersionHistoryCollection VersionHistory { get { if (_versionHistory.LoadState is LoadState.NotLoaded) { - EnsureLoaded(TopicPayload.VersionHistory).GetAwaiter().GetResult(); + ((ITopicLazyLoadable)this).EnsureLoaded(TopicPayload.VersionHistory).GetAwaiter().GetResult(); } return _versionHistory; } From a2d63a7b040fa851f3283da2adbe815c5d50af66 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 14 Jul 2026 03:00:35 -0700 Subject: [PATCH 163/337] Ensured calls to `EnsureLoaded()` are `await`ed With the migration of `EnsureLoaded()` to `async`, the callers needed to be updated to use `await`. This was especially absent in the tests. --- OnTopic.Tests/TopicRepositoryBaseTest.cs | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/OnTopic.Tests/TopicRepositoryBaseTest.cs b/OnTopic.Tests/TopicRepositoryBaseTest.cs index 98a2e08b..62fca05e 100644 --- a/OnTopic.Tests/TopicRepositoryBaseTest.cs +++ b/OnTopic.Tests/TopicRepositoryBaseTest.cs @@ -1190,7 +1190,7 @@ public async Task EnsureLoaded_ExtendedAttributesNotLoaded_MarksLoaded() { var topic = await _topicRepository.Load(11111); topic!.Attributes.LoadState = LoadState.NotLoaded; - ((ITopicLazyLoadable)topic).EnsureLoaded(TopicPayload.ExtendedAttributes); + await ((ITopicLazyLoadable)topic).EnsureLoaded(TopicPayload.ExtendedAttributes); Assert.True(((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.ExtendedAttributes)); @@ -1211,7 +1211,7 @@ public async Task EnsureLoaded_MixedBoundaries_SkipsLoadedBoundaries() { topic!.Attributes.LoadState = LoadState.NotLoaded; Assert.True(((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.Children)); - ((ITopicLazyLoadable)topic).EnsureLoaded(TopicPayload.Children | TopicPayload.ExtendedAttributes); + await ((ITopicLazyLoadable)topic).EnsureLoaded(TopicPayload.Children | TopicPayload.ExtendedAttributes); Assert.True(((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.ExtendedAttributes)); Assert.True(((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.Children)); @@ -1238,7 +1238,7 @@ public async Task EnsureLoaded_RelationshipsNotLoaded_MarksLoaded() { var topic = await _topicRepository.Load(11111); topic!.Relationships.Deferred.Add(new("_stub", 11111)); - ((ITopicLazyLoadable)topic).EnsureLoaded(TopicPayload.Relationships); + await ((ITopicLazyLoadable)topic).EnsureLoaded(TopicPayload.Relationships); Assert.True(((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.Relationships)); @@ -1264,7 +1264,7 @@ public async Task EnsureLoaded_ReferencesNotLoaded_MarksLoaded() { var topic = await _topicRepository.Load(11111); topic!.References.Deferred.Add(new("_stub", 11111)); - ((ITopicLazyLoadable)topic).EnsureLoaded(TopicPayload.References); + await ((ITopicLazyLoadable)topic).EnsureLoaded(TopicPayload.References); Assert.True(((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.References)); @@ -1404,7 +1404,7 @@ public async Task EnsureLoaded_ChildrenNotLoaded_MarksLoaded() { var topic = await _topicRepository.Load(11111); ((ITopicLazyLoadable)topic!).SetLoadState(TopicPayload.Children, LoadState.NotLoaded); - ((ITopicLazyLoadable)topic).EnsureLoaded(TopicPayload.Children); + await ((ITopicLazyLoadable)topic).EnsureLoaded(TopicPayload.Children); Assert.True(((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.Children)); @@ -1455,7 +1455,7 @@ public async Task EnsureLoaded_WithMissingRelationshipTarget_ResolvesAndConnects source.Relationships.Deferred.Add(new("_stub", 11111)); // Act: EnsureLoaded re-queries, finds the missing target, loads it, and connects the edge - _cachedTopicRepository.EnsureLoaded(source, TopicPayload.Relationships); + await _cachedTopicRepository.EnsureLoaded(source, TopicPayload.Relationships); // Relationships are now Loaded and any pre-seeded edges are connected Assert.Equal(LoadState.Loaded, source.Relationships.LoadState); @@ -1476,7 +1476,7 @@ public async Task EnsureLoaded_Relationships_AlreadyLoaded_SkipsFill() { var source = (await _cachedTopicRepository.Load(-1))!; // Act - _cachedTopicRepository.EnsureLoaded(source, TopicPayload.Relationships); + await _cachedTopicRepository.EnsureLoaded(source, TopicPayload.Relationships); // LoadState is unchanged; no fill was triggered Assert.Equal(LoadState.Loaded, source.Relationships.LoadState); From e66cea7fe365753a00cc0293db473537b2bc4395 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 14 Jul 2026 03:14:52 -0700 Subject: [PATCH 164/337] Move `ITopicLazyLoadable` methods inline Migrate most of the `ITopicLazyLoadable` methods (1007d6a7) to default interface members, which moves them away from `Topic` and directly into the interface. Since we're already using explicit interface implementations for these (248411ea), this is relatively trivial. While I was at it, I fixed some fields that weren't using collection expressions. This contributes to #111. --- OnTopic/Repositories/ITopicLazyLoadable.cs | 87 +++++++++++- OnTopic/Topic.cs | 149 +-------------------- 2 files changed, 86 insertions(+), 150 deletions(-) diff --git a/OnTopic/Repositories/ITopicLazyLoadable.cs b/OnTopic/Repositories/ITopicLazyLoadable.cs index d2905269..b1007a5a 100644 --- a/OnTopic/Repositories/ITopicLazyLoadable.cs +++ b/OnTopic/Repositories/ITopicLazyLoadable.cs @@ -32,7 +32,37 @@ public interface ITopicLazyLoadable : ITopicBackingAccessor { /// in traversal and "gating" logic that should not trigger lazy loading. /// /// One or more flags to test. - bool IsLoaded(TopicPayload payload); + bool IsLoaded(TopicPayload payload) { + + // Children + if (payload.HasFlag(TopicPayload.Children) && Children.LoadState is not LoadState.Loaded) { + return false; + } + + // Extended Attributes + if (payload.HasFlag(TopicPayload.ExtendedAttributes) && Attributes.LoadState is not LoadState.Loaded) { + return false; + } + + // Relationships + if (payload.HasFlag(TopicPayload.Relationships) && Relationships.LoadState is not LoadState.Loaded) { + return false; + } + + // References + if (payload.HasFlag(TopicPayload.References) && References.LoadState is not LoadState.Loaded) { + return false; + } + + // History + if (payload.HasFlag(TopicPayload.VersionHistory) && VersionHistory.LoadState is not LoadState.Loaded) { + return false; + } + + // Unexpected + return true; + + } /*============================================================================================================================ | METHOD: SET LOAD STATE @@ -46,7 +76,24 @@ public interface ITopicLazyLoadable : ITopicBackingAccessor { /// /// One or more flags identifying the payload to update. /// The to assign to each matched boundary's collection. - void SetLoadState(TopicPayload payload, LoadState state); + void SetLoadState(TopicPayload payload, LoadState state) { + + // Children + if (payload.HasFlag(TopicPayload.Children)) { + Children.LoadState = state; + } + + // Extended Attributes + if (payload.HasFlag(TopicPayload.ExtendedAttributes)) { + Attributes.LoadState = state; + } + + // History + if (payload.HasFlag(TopicPayload.VersionHistory)) { + VersionHistory.LoadState = state; + } + + } /*============================================================================================================================ | METHOD: FILTER PAYLOAD @@ -56,7 +103,22 @@ public interface ITopicLazyLoadable : ITopicBackingAccessor { /// redundant round trips. /// /// The requested flags to filter. - TopicPayload FilterPayload(TopicPayload payload); + TopicPayload FilterPayload(TopicPayload payload) { + + // Strip already-loaded payload + foreach (var flag in Enum.GetValues()) { + if (flag is TopicPayload.None or TopicPayload.All) { + continue; + } + if (IsLoaded(flag)) { + payload &= ~flag; + } + } + + // Return filtered payload + return payload; + + } /*============================================================================================================================ | METHODS: ENSURE LOADED @@ -75,7 +137,24 @@ public interface ITopicLazyLoadable : ITopicBackingAccessor { /// One or more flags identifying the payload that should be ensured to be loaded. /// /// An optional token that can be used to cancel the operation. - Task EnsureLoaded(TopicPayload payload, CancellationToken cancellationToken = default); + Task EnsureLoaded(TopicPayload payload, CancellationToken cancellationToken = default) { + + // Skip if the topic isn't "stamped" with the loader + if (Loader is not { } loader) { + return Task.CompletedTask; + } + + // Filter to payload that are not yet loaded + payload = FilterPayload(payload); + if (payload is TopicPayload.None) { + return Task.CompletedTask; + } + + // Ensure the appropriate payload are loaded + // (Topic)this is safe since Topic is the sole implementer of ITopicLazyLoadable + return loader.EnsureLoaded((Topic)this, payload, cancellationToken); + + } /*============================================================================================================================ | PROPERTY: LOADER diff --git a/OnTopic/Topic.cs b/OnTopic/Topic.cs index 2ec63dce..ba3c0ad4 100644 --- a/OnTopic/Topic.cs +++ b/OnTopic/Topic.cs @@ -28,11 +28,11 @@ public class Topic: ITrackDirtyKeys, ITopicLazyLoadable { private string _contentType; private string? _originalKey; private Topic? _parent; - private readonly KeyedTopicCollection _children = new(); + private readonly KeyedTopicCollection _children = []; private readonly TopicRelationshipMultiMap _relationships; private readonly TopicReferenceCollection _references; - private readonly VersionHistoryCollection _versionHistory = new(); - readonly DirtyKeyCollection _dirtyKeys = new(); + private readonly VersionHistoryCollection _versionHistory = []; + readonly DirtyKeyCollection _dirtyKeys = []; /*============================================================================================================================ | CONSTRUCTOR @@ -169,149 +169,6 @@ public KeyedTopicCollection Children { } } - /*============================================================================================================================ - | METHOD: IS LOADED - \---------------------------------------------------------------------------------------------------------------------------*/ - /// - /// Returns if every boundary flag in has already been fetched from - /// the underlying persistence store; if any one of them are . - /// - /// - /// Reads each collection's directly without touching any autoloading getter, making it safe to - /// use in traversal and "gating" logic that should not trigger lazy-loading. - /// - /// One or more flags to test. - bool ITopicLazyLoadable.IsLoaded(TopicPayload payload) { - - // Children - if (payload.HasFlag(TopicPayload.Children) && _children.LoadState is not LoadState.Loaded) { - return false; - } - - // Extended Attributes - if (payload.HasFlag(TopicPayload.ExtendedAttributes) && Attributes.LoadState is not LoadState.Loaded) { - return false; - } - - // Relationships - if (payload.HasFlag(TopicPayload.Relationships) && _relationships.LoadState is not LoadState.Loaded) { - return false; - } - - // References - if (payload.HasFlag(TopicPayload.References) && _references.LoadState is not LoadState.Loaded) { - return false; - } - - // History - if (payload.HasFlag(TopicPayload.VersionHistory) && _versionHistory.LoadState is not LoadState.Loaded) { - return false; - } - - // Unexpected - return true; - - } - - /*============================================================================================================================ - | METHOD: SET LOAD STATE - \---------------------------------------------------------------------------------------------------------------------------*/ - /// - /// Sets the for each boundary flag in to . - /// - /// - /// Mirrors : Sets each collection's directly - /// without touching any autoloading getter. Callers are responsible for passing only payload whose transition is safe; for - /// example, and should only be promoted to - /// after confirming all targets are available in the graph, since permits DeleteUnmatched on save. - /// - /// One or more flags identifying the payload to update. - /// The to assign to each matched boundary's collection. - void ITopicLazyLoadable.SetLoadState(TopicPayload payload, LoadState state) { - - // Children - if (payload.HasFlag(TopicPayload.Children)) { - _children.LoadState = state; - } - - // Extended Attributes - if (payload.HasFlag(TopicPayload.ExtendedAttributes)) { - Attributes.LoadState = state; - } - - // History - if (payload.HasFlag(TopicPayload.VersionHistory)) { - _versionHistory.LoadState = state; - } - - } - - /*============================================================================================================================ - | METHOD: FILTER PAYLOAD - \---------------------------------------------------------------------------------------------------------------------------*/ - /// - /// Returns with any already- flags cleared, so callers skip - /// redundant round-trips. - /// - /// The requested flags to filter. - TopicPayload ITopicLazyLoadable.FilterPayload(TopicPayload payload) { - - // Strip already-loaded payload - foreach (var flag in Enum.GetValues()) { - if (flag is TopicPayload.None or TopicPayload.All) { - continue; - } - if (((ITopicLazyLoadable)this).IsLoaded(flag)) { - payload &= ~flag; - } - } - - // Return filtered payload - return payload; - - } - - /*============================================================================================================================ - | METHODS: ENSURE LOADED - \---------------------------------------------------------------------------------------------------------------------------*/ - /// - /// Ensures each requested flag has been retrieved, while fetching and merging whichever of - /// them are not yet , and silently skipping those that already are. Returns immediately if - /// the loader is absent. - /// - /// - /// Callers such as a mapping or navigation service can await this to prepopulate one or more payloads before accessing - /// them, thus avoiding a synchronous block on a "cold" node. The autoloading property getters (e.g., ) - /// call this synchronously via GetAwaiter().GetResult() as an accepted sync-over-async boundary. - /// - /// - /// One or more flags identifying the payload that should be ensured to be loaded. - /// - /// An optional token that can be used to cancel the operation. - Task ITopicLazyLoadable.EnsureLoaded(TopicPayload payload, CancellationToken cancellationToken) { - - /*-------------------------------------------------------------------------------------------------------------------------- - | Skip for obvious reasons - \-------------------------------------------------------------------------------------------------------------------------*/ - if (((ITopicLazyLoadable)this).Loader is not { } loader) { - return Task.CompletedTask; - } - - /*-------------------------------------------------------------------------------------------------------------------------- - | Filter to payload that are not yet loaded - \-------------------------------------------------------------------------------------------------------------------------*/ - payload = ((ITopicLazyLoadable)this).FilterPayload(payload); - - if (payload is TopicPayload.None) { - return Task.CompletedTask; - } - - // Ensure the appropriate payload are loaded - return loader.EnsureLoaded(this, payload, cancellationToken); - - } - /*============================================================================================================================ | PROPERTY: CONTENT TYPE \---------------------------------------------------------------------------------------------------------------------------*/ From 2fe54270a79610f6a35190b3a20c23a8255cab1b Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 14 Jul 2026 03:35:44 -0700 Subject: [PATCH 165/337] Remove unused `IsDirty()`, `MarkClean()` overloads The `Topic` class had a number of `IsDirty()` and `MarkClean()` overloads not called for in `ITrackDirtyKeys`, and not actually used anywhere. Some of these are potentially useful, but since these are exclusively infrastructure related methods, the fact that they're not used by any of our `ITopicRepository` implementations is a clear sign that they're not needed (Yet). YANGI, and all. This included the `TopicCollection.AnyDirty()` extension method in the `TopicCollectionExtensions`. Removed these, as well as their accompanying tests. For the `Topic` instances, we do still require one `key` overload, so those are consolidated into one implementation. I also deleted tests that verified these overload, while also rewriting `MarkClean_NewTopic_RemainsDirty` to use the consolidate overloads. --- OnTopic.Tests/TopicQueryingTest.cs | 36 ------ OnTopic.Tests/TopicReferenceCollectionTest.cs | 20 ---- OnTopic.Tests/TopicTest.cs | 88 ++------------ OnTopic/Querying/TopicCollectionExtensions.cs | 17 --- OnTopic/Topic.cs | 111 ++++-------------- 5 files changed, 34 insertions(+), 238 deletions(-) diff --git a/OnTopic.Tests/TopicQueryingTest.cs b/OnTopic.Tests/TopicQueryingTest.cs index f822404e..0316125f 100644 --- a/OnTopic.Tests/TopicQueryingTest.cs +++ b/OnTopic.Tests/TopicQueryingTest.cs @@ -279,42 +279,6 @@ public async Task GetContentType_InvalidType_ReturnsNull() { } - /*============================================================================================================================ - | TEST: ANY DIRTY: DIRTY COLLECTION: RETURN TRUE - \---------------------------------------------------------------------------------------------------------------------------*/ - /// - /// Given a with at least one that , - /// returns true. - /// - [Fact] - public void AnyDirty_DirtyCollection_ReturnTrue() { - - var topics = new TopicCollection { - new("Test", "Page") - }; - - Assert.True(topics.AnyDirty()); - - } - - /*============================================================================================================================ - | TEST: ANY DIRTY: CLEAN COLLECTION: RETURN FALSE - \---------------------------------------------------------------------------------------------------------------------------*/ - /// - /// Given a with no s that are , - /// returns false. - /// - [Fact] - public void AnyDirty_CleanCollection_ReturnFalse() { - - var topics = new TopicCollection { - new("Test", "Page", null, 1) - }; - - Assert.False(topics.AnyDirty()); - - } - /*============================================================================================================================ | TEST: ANY NEW: CONTAINS NEW: RETURN TRUE \---------------------------------------------------------------------------------------------------------------------------*/ diff --git a/OnTopic.Tests/TopicReferenceCollectionTest.cs b/OnTopic.Tests/TopicReferenceCollectionTest.cs index 70cef0eb..09847d20 100644 --- a/OnTopic.Tests/TopicReferenceCollectionTest.cs +++ b/OnTopic.Tests/TopicReferenceCollectionTest.cs @@ -264,26 +264,6 @@ public void SetValue_NullReference_TopicRemoved() { } - /*============================================================================================================================ - | TEST: ADD: NEW REFERENCE: TOPIC IS DIRTY - \---------------------------------------------------------------------------------------------------------------------------*/ - /// - /// Assembles a new , adds a new reference, and confirms that - /// is correctly set. - /// - [Fact] - public void Add_NewReference_TopicIsDirty() { - - var topic = new Topic("Topic", "Page", null, 1); - var reference = new Topic("Reference", "Page", null, 2); - - topic.References.SetValue("Reference", reference); - - Assert.True(topic.IsDirty(true)); - Assert.False(reference.IsDirty(true)); - - } - /*============================================================================================================================ | TEST: GET TOPIC: EXISTING REFERENCE: RETURNS TOPIC \---------------------------------------------------------------------------------------------------------------------------*/ diff --git a/OnTopic.Tests/TopicTest.cs b/OnTopic.Tests/TopicTest.cs index e7be03a5..b562b35c 100644 --- a/OnTopic.Tests/TopicTest.cs +++ b/OnTopic.Tests/TopicTest.cs @@ -382,7 +382,7 @@ public void BaseTopic_SetToNull_RemovesValue() { | IS DIRTY: NEW TOPIC: RETURNS TRUE \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Creates a new topic, and confirms that returns true. + /// Creates a new topic, and confirms that returns true. /// [Fact] public void IsDirty_NewTopic_ReturnsTrue() => @@ -392,7 +392,7 @@ public void IsDirty_NewTopic_ReturnsTrue() => | IS DIRTY: EXISTING TOPIC: RETURNS FALSE \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Creates an existing topic, and confirms that returns false. + /// Creates an existing topic, and confirms that returns false. /// [Fact] public void IsDirty_ExistingTopic_ReturnsFalse() => @@ -402,8 +402,8 @@ public void IsDirty_ExistingTopic_ReturnsFalse() => | IS DIRTY: CHANGE KEY: RETURNS TRUE \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Creates an existing topic, changes the , and confirms that returns true. + /// Creates an existing topic, changes the , and confirms that returns + /// true. /// [Fact] public void IsDirty_ChangeKey_ReturnsTrue() => @@ -434,84 +434,12 @@ public void IsDirty_ExistingValue_RemainsClean() { } - /*============================================================================================================================ - | IS DIRTY: CHANGE COLLECTIONS: RETURNS TRUE - \---------------------------------------------------------------------------------------------------------------------------*/ - /// - /// Creates an existing topic, changes the , , and collections, and confirms that returns - /// true. - /// - [Fact] - public void IsDirty_ChangeCollections_ReturnsTrue() { - - var topic = new Topic("Topic", "Page", null, 1); - var related = new Topic("Related", "Page", null, 2); - - topic.Attributes.SetValue("Related", related.Key); - topic.References.SetValue("Related", related); - topic.Relationships.SetValue("Related", related); - - Assert.True(topic.IsDirty(true)); - Assert.True(topic.IsDirty("Related", true)); - - } - - /*============================================================================================================================ - | MARK CLEAN: CHANGE COLLECTIONS: RESETS IS DIRTY - \---------------------------------------------------------------------------------------------------------------------------*/ - /// - /// Creates an existing topic, changes the , , and collections, and confirms that resets the - /// value of . - /// - [Fact] - public void MarkClean_ChangeCollections_ResetIsDirty() { - - var topic = new Topic("Topic", "Page", null, 1); - var related = new Topic("Related", "Page", null, 2); - - topic.Attributes.SetValue("Related", related.Key); - topic.References.SetValue("Related", related); - topic.Relationships.SetValue("Related", related); - - topic.MarkClean(true); - - Assert.False(topic.IsDirty(true)); - - } - - /*============================================================================================================================ - | MARK CLEAN: INCLUDE COLLECTIONS: RESETS IS DIRTY - \---------------------------------------------------------------------------------------------------------------------------*/ - /// - /// Creates an existing topic, changes the , , and collections, and confirms that resets the value - /// of . - /// - [Fact] - public void MarkClean_IncludeCollections_ResetsIsDirty() { - - var topic = new Topic("Topic", "Page", null, 1); - var related = new Topic("Related", "Page", null, 2); - - topic.Attributes.SetValue("Related", related.Key); - topic.References.SetValue("Related", related); - topic.Relationships.SetValue("Related", related); - - topic.MarkClean("Related", true); - - Assert.False(topic.IsDirty("Related", true)); - Assert.False(topic.IsDirty(true)); - - } - /*============================================================================================================================ | MARK CLEAN: NEW TOPIC: REMAINS DIRTY \---------------------------------------------------------------------------------------------------------------------------*/ /// /// Creates a new and confirms that does not reset the value of - /// . Topics that are marked as cannot be clean. + /// . Topics that are marked as cannot be clean. /// [Fact] public void MarkClean_NewTopic_RemainsDirty() { @@ -519,11 +447,11 @@ public void MarkClean_NewTopic_RemainsDirty() { var topic = new Topic("Topic", "Page"); topic.Attributes.SetValue("Attribute", "Test"); - topic.MarkClean("Attribute", true); - topic.MarkClean(true); + topic.MarkClean("Attribute"); + topic.MarkClean(); Assert.True(topic.IsDirty()); - Assert.True(topic.IsDirty("Attribute", true)); + Assert.True(topic.IsDirty("Attribute")); } diff --git a/OnTopic/Querying/TopicCollectionExtensions.cs b/OnTopic/Querying/TopicCollectionExtensions.cs index 8ce85a36..315d4a5a 100644 --- a/OnTopic/Querying/TopicCollectionExtensions.cs +++ b/OnTopic/Querying/TopicCollectionExtensions.cs @@ -16,23 +16,6 @@ namespace OnTopic.Querying; /// public static class TopicCollectionExtensions { - /*============================================================================================================================ - | METHOD: ANY DIRTY? - \---------------------------------------------------------------------------------------------------------------------------*/ - /// - /// Determines whether any of the instances in the collection are marked as . - /// - /// - /// This does not determine if the collection itself is dirty—it only determines if any instances in - /// the collection are . This distinction is important. For example, if a clean is added to the collection, then the collection will be dirty—but - /// will be false. - /// - /// The collection of instances to operate against. - /// Returns true if any of the instances are . - public static bool AnyDirty(this IEnumerable topics) => topics.Any(t => t.IsDirty(true)); - /*============================================================================================================================ | METHOD: ANY NEW? \---------------------------------------------------------------------------------------------------------------------------*/ diff --git a/OnTopic/Topic.cs b/OnTopic/Topic.cs index ba3c0ad4..870f05f2 100644 --- a/OnTopic/Topic.cs +++ b/OnTopic/Topic.cs @@ -589,111 +589,52 @@ public string GetWebPath() { | METHOD: IS DIRTY? \---------------------------------------------------------------------------------------------------------------------------*/ - /// - public bool IsDirty() => IsDirty(false); - /// - /// Determines if the topic is dirty, optionally checking and . + /// Determines whether the 's key attributes—i.e., its , , and + /// other tracked keys—have been modified. This does not evaluate the (overall), , or collections; query those through their own methods. /// - /// - /// Determines if , , and should be checked. - /// - /// - /// Optionally excludes s whose keys start with LastModified. This is useful for - /// excluding the byline (LastModifiedBy) and dateline (LastModified) since these values are automatically - /// generated by e.g. the OnTopic Editor and, thus, may be irrelevant updates if no other attribute values have changed. - /// - /// - /// Returns true if the , , or, optionally, any collections have been - /// modified. - /// - public bool IsDirty(bool checkCollections, bool excludeLastModified = false) { - if (IsNew || _dirtyKeys.IsDirty()) { - return true; - } - else if (!checkCollections) { - return false; - } - else if ( - Attributes.IsDirty(excludeLastModified) || - _relationships.IsDirty() || - _references.IsDirty() - ) { - return true; - } - return false; - } + /// Returns true if the or have been modified. + public bool IsDirty() => IsNew || _dirtyKeys.IsDirty(); - /// - public bool IsDirty(string key) => IsDirty(key, false); - - /// - public bool IsDirty(string key, bool checkCollections) { - if (IsNew || _dirtyKeys.IsDirty(key)) { - return true; - } - else if (!checkCollections) { - return false; - } - else if ( - Attributes.IsDirty(key) || - _relationships.IsDirty(key) || - _references.IsDirty(key) - ) { - return true; - } - return false; - } + /// + /// Determines whether the on the key attributes has been modified. This does + /// not evaluate the (overall), , or + /// collections; query those through their own methods. + /// + /// The key of the attribute to check. + /// Returns true if the has been modified. + public bool IsDirty(string key) => IsNew || _dirtyKeys.IsDirty(key); /*============================================================================================================================ | METHOD: MARK CLEAN \---------------------------------------------------------------------------------------------------------------------------*/ - /// - public void MarkClean() => MarkClean(false); - /// - /// Resets the status of the —and, optionally, that of all collections, using - /// the parameter. + /// Resets the status of the 's own record, covering its key attributes. This + /// does not affect the (overall), , or + /// collections; reset those through their own methods. /// - /// - /// Determines if , , and should be included. - /// - /// - /// The value that the attributes were last saved. This corresponds to the . - /// - public void MarkClean(bool includeCollections, DateTime? version = null) { + public void MarkClean() { if (IsNew) { return; } _dirtyKeys.MarkClean(); - if (includeCollections) { - Attributes.MarkClean(version); - _relationships.MarkClean(); - _references.MarkClean(); - } - } - - /// - public void MarkClean(string key) { - if (IsNew) { - return; - } - MarkClean(key, false); } - /// - public void MarkClean(string key, bool includeCollections) { + /// + /// Resets the status of the on the 's own record, + /// covering its key attributes. This does not affect the (overall), , or collections; reset those through their own methods. + /// + /// The key of the attribute to mark as clean. + public void MarkClean(string key) { if (IsNew) { return; } _dirtyKeys.MarkClean(key); - if (includeCollections) { - Attributes.MarkClean(key); - _relationships.MarkClean(key); - _references.MarkClean(key); - } } #endregion From 687d1ef984cf80070be126dcd78ced661172176e Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 14 Jul 2026 04:05:03 -0700 Subject: [PATCH 166/337] Introduced new `DeferredAssociationCollection` The new `DeferredAssociationCollection` formalizes the previously introduced `Deferred` collection property (f210866e) with a more specialized collection. This allows it to introduce custom `Remove()` and `SetValue()` methods, which help centralize some logic that was starting to leak beyond it. Most notably, the `Deferred` collections shouldn't have duplicate keys. To avoid this, previously, I'd taken a sledgehammer approach by clearing the `Deferred` collection entirely processing a `Load()` or `EnsureLoaded()` which included associations (e.g., `TopicPayload.Children` in `EnsureLoaded()`; dc975bf2). This pertains to the lazy-loading infrastructure (#111). --- .../DeferredAssociationCollection.cs | 86 +++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 OnTopic/Associations/DeferredAssociationCollection.cs diff --git a/OnTopic/Associations/DeferredAssociationCollection.cs b/OnTopic/Associations/DeferredAssociationCollection.cs new file mode 100644 index 00000000..ce375b3f --- /dev/null +++ b/OnTopic/Associations/DeferredAssociationCollection.cs @@ -0,0 +1,86 @@ +/*============================================================================================================================== +| Author Ignia, LLC +| Client Ignia, LLC +| Project Topics Library +\=============================================================================================================================*/ +using System.Collections.ObjectModel; + +namespace OnTopic.Associations; + +/*============================================================================================================================== +| CLASS: DEFERRED ASSOCIATION COLLECTION +\-----------------------------------------------------------------------------------------------------------------------------*/ +/// +/// Represents a collection of records pending resolution via lazy loading; i.e., +/// relationships or references to targets that weren't available in the topic graph when first loaded. +/// +/// +/// Deduplicates on add so that repeated loads don't accumulate redundant entries. Identity isn't uniform: References are +/// single-valued, so an entry's identity is its alone; relationships are multivalued, +/// so an entry's identity is the full and +/// pair. This mirrors the asymmetry already represented in and . +/// +public class DeferredAssociationCollection: Collection { + + /*============================================================================================================================ + | PRIVATE VARIABLES + \---------------------------------------------------------------------------------------------------------------------------*/ + readonly bool _singleValued; + + /*============================================================================================================================ + | CONSTRUCTOR + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Initializes a new instance of the class. + /// + /// + /// Determines whether entries are identified by alone (true for references), + /// or by the full and pair (false + /// for relationships). + /// + public DeferredAssociationCollection(bool singleValued = false) { + _singleValued = singleValued; + } + + /*============================================================================================================================ + | METHOD: SET VALUE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Registers a deferred association, replacing any existing entry that shares the new entry's identity. + /// + /// The relationship or reference key under which the association is registered. + /// The of the target topic to be resolved. + public void SetValue(string key, int topicId) { + Remove(key, _singleValued? null : topicId); + Add(new(key, topicId)); + } + + /*============================================================================================================================ + | METHOD: REMOVE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Removes the deferred association(s) matching the given identity. + /// + /// + /// When is omitted, every entry registered under is removed; otherwise + /// only the exact and pair is removed. + /// + /// The relationship or reference key of the association(s) to remove. + /// The of the target topic, if scoping the removal to a single entry. + /// Returns true if one or more entries were removed; otherwise, false. + public bool Remove(string key, int? topicId = null) { + var removed = false; + for (var i = Count - 1; i >= 0; i--) { + if (this[i].Key == key && (topicId is null || this[i].TopicId == topicId)) { + RemoveAt(i); + removed = true; + if (topicId is not null) { + break; + } + } + } + return removed; + } + +} //Class \ No newline at end of file From f2add3acb518f633e5aa9e5e422583b8cf528dcb Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 14 Jul 2026 04:18:10 -0700 Subject: [PATCH 167/337] Implemented new `DeferredAssociationCollection` This implements the newly introduced `DeferredAssociationCollection` as the type for the `Deferred` properties. As a result of the new `SetValue()` method, which automatically deduplicates `DeferredAssociation` items, we no longer need to preemptively `Clear()` the `Deferred` collection when `EnsureLoaded()` must reload the parent as e.g., part of `TopicPayload.Children`. This relates to #111. --- OnTopic.Data.Sql/SqlDataReaderExtensions.cs | 4 ++-- OnTopic.Data.Sql/SqlTopicRepository.cs | 11 +++-------- OnTopic/Associations/TopicReferenceCollection.cs | 16 +++------------- .../Associations/TopicRelationshipMultiMap.cs | 9 ++------- 4 files changed, 10 insertions(+), 30 deletions(-) diff --git a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs index 26ba8c23..91ffef97 100644 --- a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs +++ b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs @@ -465,7 +465,7 @@ internal static void SetRelationships(this IDataReader reader, TopicIndex topics // When the target is absent, defer it for resolution on next access if (related is null) { - rawTopic.Relationships.Deferred.Add(new(relationshipKey, targetTopicId)); + rawTopic.Relationships.Deferred.SetValue(relationshipKey, targetTopicId); return; } @@ -526,7 +526,7 @@ internal static void SetReferences(this IDataReader reader, TopicIndex topics, b // When the target isn't (yet) available, defer it to be lazy loaded when the references are accessed else { - rawTopic.References.Deferred.Add(new(referenceKey, targetTopicId.Value)); + rawTopic.References.Deferred.SetValue(referenceKey, targetTopicId.Value); return; } diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index 8426a7ff..b75cdf84 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -431,8 +431,9 @@ public virtual async Task EnsureLoaded(Topic topic, TopicPayload payload, Cancel | Process database query >--------------------------------------------------------------------------------------------------------------------------- | Use the full live graph as the topic index so already-resident relationship targets are found without extra round-trips. - | When filling Children, associations for the parent/seed topic are re-fetched alongside the children's; stale deferred - | entries are cleared before processing to prevent duplicates from accumulating in the Deferred collection. + | When filling Children, associations for the parent/seed topic are re-fetched alongside the children's; the + | DeferredAssociationCollection.SetValue() deduplicate those values so reprocessing doesn't accumulate duplicate entries in + | the Deferred collection. \-------------------------------------------------------------------------------------------------------------------------*/ var topics = topic.GetRootTopic().GetTopicIndex(); var rawTopic = (ITopicBackingAccessor)topic; @@ -465,12 +466,6 @@ public virtual async Task EnsureLoaded(Topic topic, TopicPayload payload, Cancel reader.SetExtendedAttributes(topics, markDirty: false, preserveDirty: true); } - // Clear stale deferred entries on the parent/seed topic before its associations are re-processed alongside children - if (payload.HasFlag(TopicPayload.Children)) { - rawTopic.Relationships.Deferred.Clear(); - rawTopic.References.Deferred.Clear(); - } - // Relationships (will be empty, unless loading children) await reader.NextResultAsync(cancellationToken).ConfigureAwait(false); while (await reader.ReadAsync(cancellationToken).ConfigureAwait(false)) { diff --git a/OnTopic/Associations/TopicReferenceCollection.cs b/OnTopic/Associations/TopicReferenceCollection.cs index 48a8d414..c24254c7 100644 --- a/OnTopic/Associations/TopicReferenceCollection.cs +++ b/OnTopic/Associations/TopicReferenceCollection.cs @@ -68,7 +68,7 @@ public TopicReferenceCollection(Topic parentTopic) : base(parentTopic) { } /// by calling the 's Load() method, assuming the topics haven't since been introduced /// to the topic graph. /// - public Collection Deferred { get; } = new(); + public DeferredAssociationCollection Deferred { get; } = new(singleValued: true); /*============================================================================================================================ | INSERT ITEM @@ -89,12 +89,7 @@ protected override void InsertItem(int index, TopicReferenceRecord item) { /*-------------------------------------------------------------------------------------------------------------------------- | Remove any pending deferred entry for this reference key \-------------------------------------------------------------------------------------------------------------------------*/ - for (var i = Deferred.Count - 1; i >= 0; i--) { - if (Deferred[i].Key == item.Key) { - Deferred.RemoveAt(i); - break; - } - } + Deferred.Remove(item.Key); /*-------------------------------------------------------------------------------------------------------------------------- | Handle recipricol references @@ -127,12 +122,7 @@ protected override void SetItem(int index, TopicReferenceRecord item) { /*-------------------------------------------------------------------------------------------------------------------------- | Remove any pending deferred entry for this reference key \-------------------------------------------------------------------------------------------------------------------------*/ - for (var i = Deferred.Count - 1; i >= 0; i--) { - if (Deferred[i].Key == item.Key) { - Deferred.RemoveAt(i); - break; - } - } + Deferred.Remove(item.Key); /*-------------------------------------------------------------------------------------------------------------------------- | Handle recipricol references diff --git a/OnTopic/Associations/TopicRelationshipMultiMap.cs b/OnTopic/Associations/TopicRelationshipMultiMap.cs index 2672fa19..9fe24f4d 100644 --- a/OnTopic/Associations/TopicRelationshipMultiMap.cs +++ b/OnTopic/Associations/TopicRelationshipMultiMap.cs @@ -213,12 +213,7 @@ internal void SetValue(string relationshipKey, Topic topic, bool? markDirty, boo } // Remove any pending deferred entry for this relationship/target pair - for (var i = Deferred.Count - 1; i >= 0; i--) { - if (Deferred[i].Key == relationshipKey && Deferred[i].TopicId == topic.Id) { - Deferred.RemoveAt(i); - break; - } - } + Deferred.Remove(relationshipKey, topic.Id); } /*-------------------------------------------------------------------------------------------------------------------------- @@ -275,7 +270,7 @@ public void SetTopic(string relationshipKey, Topic topic, bool? isDirty, bool is /// by calling the 's Load() method, assuming the topics haven't since been introduced /// to the topic graph. /// - public Collection Deferred { get; } = new(); + public DeferredAssociationCollection Deferred { get; } = new(); /*============================================================================================================================ | METHOD: IS DIRTY? From 50f4376c730203e3bca56ea788845df19772c70f Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 14 Jul 2026 14:35:20 -0700 Subject: [PATCH 168/337] Rely on constructor `isIncoming` over method param Previously, `isIncoming` was passed to the `TopicRelationshipMultiMap` constructor as well as its `SetValue()` and `Remove()` methods. If `isComing` was set in the constructor but not in `SetValue()` or `Remove()`, then an exception would be thrown telling the user that this was an incoming collection, so calls must include `isIncoming`. This was meant as a type of failsafe. That said, these were largely redundant. And since this is really internal infrastructure that only makes sense on the two places it exists, due to how tied it is to `Topic`, I don't think this provides much value. Still, to be safe, I've changed the constructor from `public` to `internal` to make sure it's not used externally. If external developers need something like this, they're better served by using the underlying `TopicMultiMap`, which is the same data structure without all of the `Topic` specific business logic placed on top. (Or, if there's demand, I could create a `TrackableTopicMultiMap` which includes the `ITrackDirtyKeys`, but not the `IncomingRelationships` logic, which would map to `TrackedRecordCollection` for `TopicReferenceCollection`.) As part of this, I also deleted two obsolete `SetTopic()` and `RemoveTopic()` overloads that pointed to the now deleted `SetValue()` and `Remove()` overloads. These were already scheduled to be removed this upcoming release, but since their pointers are now dead as well, this is a good time to finalize that. I also removed two now-unnecessary tests (related to the thrown error) and replaced them with explicit tests for confirming that `isIncoming` works. --- .../TopicRelationshipMultiMapTest.cs | 46 ++++++----- .../Associations/TopicReferenceCollection.cs | 11 +-- .../Associations/TopicRelationshipMultiMap.cs | 77 +++---------------- 3 files changed, 41 insertions(+), 93 deletions(-) diff --git a/OnTopic.Tests/TopicRelationshipMultiMapTest.cs b/OnTopic.Tests/TopicRelationshipMultiMapTest.cs index 5aa52a67..9b37da3d 100644 --- a/OnTopic.Tests/TopicRelationshipMultiMapTest.cs +++ b/OnTopic.Tests/TopicRelationshipMultiMapTest.cs @@ -134,44 +134,48 @@ public void SetValue_CreatesIncomingRelationship() { } /*============================================================================================================================ - | TEST: SET VALUE: INCOMING RELATIONSHIPS: THROWS EXCEPTION + | TEST: SET VALUE: INCOMING RELATIONSHIPS: WRITES ONE-WAY \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Attempts to set a relationship on a that is marked as isIncoming - /// without setting the isIncoming parameter on and verifies that a is thrown. + /// Calls directly against a that is marked as isIncoming and confirms it writes the entry locally without + /// also writing the reciprocal relationship to on the target topic. /// [Fact] - public void SetValue_IncomingRelationships_ThrowsException() { + public void SetValue_IncomingRelationships_WritesOneWay() { var parent = new Topic("Parent", "Page"); var related = new Topic("Related", "Page"); var relationships = new TopicRelationshipMultiMap(parent, true); - Assert.Throws(() => - relationships.SetValue("Friends", related) - ); + relationships.SetValue("Friends", related); + + Assert.Contains(related, relationships.GetValues("Friends")); + Assert.Empty(related.IncomingRelationships.GetValues("Friends")); } /*============================================================================================================================ - | TEST: REMOVE: INCOMING RELATIONSHIPS: THROWS EXCEPTION + | TEST: REMOVE: INCOMING RELATIONSHIPS: REMOVES ONE-WAY \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Attempts to remove a relationship from a that is marked as isIncoming - /// without setting the isIncoming parameter on and verifies that a is thrown. + /// Calls directly against a that is marked as isIncoming and confirms it removes the entry locally without also + /// removing the reciprocal relationship from on the target topic. /// [Fact] - public void Remove_IncomingRelationships_ThrowsException() { + public void Remove_IncomingRelationships_RemovesOneWay() { var parent = new Topic("Parent", "Page"); var related = new Topic("Related", "Page"); var relationships = new TopicRelationshipMultiMap(parent, true); - Assert.Throws(() => - relationships.Remove("Friends", related) - ); + relationships.SetValue("Friends", related); + related.IncomingRelationships.SetValue("Friends", parent); + relationships.Remove("Friends", related); + + Assert.Empty(relationships.GetValues("Friends")); + Assert.Contains(parent, related.IncomingRelationships.GetValues("Friends")); } @@ -472,7 +476,7 @@ public void Clear_NoTopics_IsNotDirty() { /// /// Adds an existing to a and confirms that returns false if is called with the markDirty parameter set to false. + /// Topic, Boolean?)"/> is called with the markDirty parameter set to false. /// [Fact] public void SetValue_MarkNotDirty_IsNotDirty() { @@ -493,8 +497,8 @@ public void SetValue_MarkNotDirty_IsNotDirty() { /// /// Adds an existing to a associated with a and confirms that returns true - /// even if is called with the - /// markDirty parameter set to false. + /// even if is called with the markDirty + /// parameter set to false. /// [Fact] public void SetValue_NewParent_IsDirty() { @@ -515,8 +519,8 @@ public void SetValue_NewParent_IsDirty() { /// /// Adds a new to a associated with an existing and confirms that returns true even if is called with the markDirty parameter - /// set to false. + /// "TopicRelationshipMultiMap.SetValue(String, Topic, Boolean?)"/> is called with the markDirty parameter set to + /// false. /// [Fact] public void SetValue_NewTopic_IsDirty() { diff --git a/OnTopic/Associations/TopicReferenceCollection.cs b/OnTopic/Associations/TopicReferenceCollection.cs index c24254c7..032593b4 100644 --- a/OnTopic/Associations/TopicReferenceCollection.cs +++ b/OnTopic/Associations/TopicReferenceCollection.cs @@ -3,7 +3,6 @@ | Client Ignia, LLC | Project Topics Library \=============================================================================================================================*/ -using System.Collections.ObjectModel; using OnTopic.Collections.Specialized; using OnTopic.Repositories; @@ -94,7 +93,7 @@ protected override void InsertItem(int index, TopicReferenceRecord item) { /*-------------------------------------------------------------------------------------------------------------------------- | Handle recipricol references \-------------------------------------------------------------------------------------------------------------------------*/ - item.Value?.IncomingRelationships.SetValue(item.Key, AssociatedTopic, null, true); + item.Value?.IncomingRelationships.SetValue(item.Key, AssociatedTopic); } @@ -127,8 +126,10 @@ protected override void SetItem(int index, TopicReferenceRecord item) { /*-------------------------------------------------------------------------------------------------------------------------- | Handle recipricol references \-------------------------------------------------------------------------------------------------------------------------*/ - existingItem.Value?.IncomingRelationships.Remove(existingItem.Key, AssociatedTopic, true); - item?.Value?.IncomingRelationships.SetValue(item.Key, AssociatedTopic, null, true); + if (existingItem.Value != item.Value) { + existingItem.Value?.IncomingRelationships.Remove(existingItem.Key, AssociatedTopic); + item?.Value?.IncomingRelationships.SetValue(item.Key, AssociatedTopic); + } } @@ -143,7 +144,7 @@ protected override sealed void RemoveItem(int index) { \-------------------------------------------------------------------------------------------------------------------------*/ var existing = this[index]; - existing.Value?.IncomingRelationships.Remove(existing.Key, AssociatedTopic, true); + existing.Value?.IncomingRelationships.Remove(existing.Key, AssociatedTopic); /*-------------------------------------------------------------------------------------------------------------------------- | Provide base logic diff --git a/OnTopic/Associations/TopicRelationshipMultiMap.cs b/OnTopic/Associations/TopicRelationshipMultiMap.cs index 9fe24f4d..37057749 100644 --- a/OnTopic/Associations/TopicRelationshipMultiMap.cs +++ b/OnTopic/Associations/TopicRelationshipMultiMap.cs @@ -3,7 +3,6 @@ | Client Ignia, LLC | Project Topics Library \=============================================================================================================================*/ -using System.Collections.ObjectModel; using OnTopic.Collections.Specialized; using OnTopic.Querying; using OnTopic.Repositories; @@ -41,11 +40,11 @@ public class TopicRelationshipMultiMap : ReadOnlyTopicMultiMap, ITrackDirtyKeys /// /// The constructor requires a reference to a instance, which the related topics are to be associated /// with. This will be used when setting incoming relationships. In addition, a - /// may be set as if it is specifically intended to track incoming relationships; if this is - /// not set, then it will not allow incoming relationships to be set via the internal overload. + /// may be set as if it is specifically intended to track incoming relationships; when set, + /// and won't set the reciprocal + /// relationship, since in this case represents that reciprocal. /// - public TopicRelationshipMultiMap(Topic parent, bool isIncoming = false): base(new()) { + internal TopicRelationshipMultiMap(Topic parent, bool isIncoming = false): base(new()) { _parent = parent; _isIncoming = isIncoming; _storage = base.Source; @@ -90,21 +89,7 @@ public void Clear(string relationshipKey) { /// Returns true if the is removed; returns false if either the specified or the cannot be found. /// - public bool Remove(string relationshipKey, Topic topic) => Remove(relationshipKey, topic, false); - - /// - /// Removes a specific object associated with a specific relationship key. - /// - /// The key of the relationship. - /// The topic to be removed. - /// - /// Notes that this is setting an internal relationship, and thus shouldn't set the reciprocal relationship. - /// - /// - /// Returns true if the is removed; returns false if either the relationship key or the - /// cannot be found. - /// - internal bool Remove(string relationshipKey, Topic topic, bool isIncoming) { + public bool Remove(string relationshipKey, Topic topic) { /*-------------------------------------------------------------------------------------------------------------------------- | Validate contracts @@ -115,14 +100,8 @@ internal bool Remove(string relationshipKey, Topic topic, bool isIncoming) { /*-------------------------------------------------------------------------------------------------------------------------- | Remove reciprocal relationship, if appropriate \-------------------------------------------------------------------------------------------------------------------------*/ - if (!isIncoming) { - if (_isIncoming) { - throw new InvalidOperationException( - "You are attempting to remove an incoming relationship on a TopicRelationshipMultiMap that is not flagged as " + - nameof(isIncoming) - ); - } - topic.IncomingRelationships.Remove(relationshipKey, _parent, true); + if (!_isIncoming) { + topic.IncomingRelationships.Remove(relationshipKey, _parent); } /*-------------------------------------------------------------------------------------------------------------------------- @@ -150,12 +129,6 @@ internal bool Remove(string relationshipKey, Topic topic, bool isIncoming) { [Obsolete($"The {nameof(RemoveTopic)} method has been renamed to {nameof(Remove)}.", true)] public bool RemoveTopic(string relationshipKey, Topic topic) => Remove(relationshipKey, topic); - /// - [ExcludeFromCodeCoverage] - [Obsolete($"The {nameof(RemoveTopic)} method has been renamed to {nameof(Remove)}.", true)] - public bool RemoveTopic(string relationshipKey, Topic topic, bool isIncoming) => - Remove(relationshipKey, topic, isIncoming); - /*============================================================================================================================ | METHOD: SET VALUE \---------------------------------------------------------------------------------------------------------------------------*/ @@ -171,25 +144,7 @@ public bool RemoveTopic(string relationshipKey, Topic topic, bool isIncoming) => /// /// Optionally forces the collection to an state, assuming the topic was set. /// - public void SetValue(string relationshipKey, Topic topic, bool? markDirty = null) - => SetValue(relationshipKey, topic, markDirty, false); - - /// - /// Ensures that an incoming is associated with the specified . - /// - /// - /// If a relationship by a given is not currently established, it will automatically be - /// created. - /// - /// The key of the relationship. - /// The topic to be added, if it doesn't already exist. - /// - /// Notes that this is setting an internal relationship, and thus shouldn't set the reciprocal relationship. - /// - /// - /// Optionally forces the collection to an state, assuming the topic was set. - /// - internal void SetValue(string relationshipKey, Topic topic, bool? markDirty, bool isIncoming) { + public void SetValue(string relationshipKey, Topic topic, bool? markDirty = null) { /*-------------------------------------------------------------------------------------------------------------------------- | Validate contracts @@ -219,14 +174,8 @@ internal void SetValue(string relationshipKey, Topic topic, bool? markDirty, boo /*-------------------------------------------------------------------------------------------------------------------------- | Create reciprocal relationship, if appropriate \-------------------------------------------------------------------------------------------------------------------------*/ - if (!isIncoming) { - if (_isIncoming) { - throw new InvalidOperationException( - "You are attempting to set an incoming relationship on a TopicRelationshipMultiMap that is not flagged as " + - nameof(isIncoming) - ); - } - topic.IncomingRelationships.SetValue(relationshipKey, _parent, markDirty, true); + if (!_isIncoming) { + topic.IncomingRelationships.SetValue(relationshipKey, _parent, markDirty); } } @@ -236,12 +185,6 @@ internal void SetValue(string relationshipKey, Topic topic, bool? markDirty, boo [Obsolete($"The {nameof(SetTopic)} method has been renamed to {nameof(SetValue)}.", true)] public void SetTopic(string relationshipKey, Topic topic, bool? isDirty = null) => SetValue(relationshipKey, topic, isDirty); - /// - [ExcludeFromCodeCoverage] - [Obsolete($"The {nameof(SetTopic)} method has been renamed to {nameof(SetValue)}.", true)] - public void SetTopic(string relationshipKey, Topic topic, bool? isDirty, bool isIncoming) => - SetValue(relationshipKey, topic, isDirty, isIncoming); - /*============================================================================================================================ | PROPERTY: LOAD STATE \---------------------------------------------------------------------------------------------------------------------------*/ From 482a4ff0dad1f9349aea6f8693a8d14ae9d530ab Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 14 Jul 2026 14:37:53 -0700 Subject: [PATCH 169/337] Mark `Source` as `private protected` The `ReadOnlyTopicMultiMap` promises to be read-only, and yet its `Source` property provides a backdoor that violates that promise. This is intentional for internal inheritors that need to update the collection without allowing consumers to update it. But `Source` being protected allows external consumers to potentially modify it. The fix for this is to make it `private protected`, thus allowing internal inheritors, such as `TopicRelationshipMultiMap`, to write to it, while otherwise hiding it from external callers. --- OnTopic/Collections/Specialized/ReadOnlyTopicMultiMap.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/OnTopic/Collections/Specialized/ReadOnlyTopicMultiMap.cs b/OnTopic/Collections/Specialized/ReadOnlyTopicMultiMap.cs index 2872119f..7cc6de19 100644 --- a/OnTopic/Collections/Specialized/ReadOnlyTopicMultiMap.cs +++ b/OnTopic/Collections/Specialized/ReadOnlyTopicMultiMap.cs @@ -41,7 +41,7 @@ public ReadOnlyTopicMultiMap(TopicMultiMap source) { /// "ReadOnlyTopicMultiMap(TopicMultiMap)"/> constructor. /// [NotNull, DisallowNull] - protected TopicMultiMap? Source { get; init; } + private protected TopicMultiMap? Source { get; init; } /*============================================================================================================================ | PROPERTY: KEYS From 1b602d099ded374a76b63c4dd2dac9d0cba26d80 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 14 Jul 2026 14:54:44 -0700 Subject: [PATCH 170/337] Ensure reset of `Attributes.LoadState` We'll be moving toward merging topics in a subsequent `Load()` version to account for differential `TopicPayload`. In preparation for that, I'm making sure that if `HasExtendedAttributes` is null or false that `LoadState` is being set to `Loaded`. Previously, if this was true, it was set to `NotLoaded`, but that didn't account for resetting it once we have this information. The preexisting logic may still be buggy, because it assumes if the value is true, then it's not loaded. But in a merge case, that could be because it was previously loaded. That'll need to be addressed as part of the actual merge project. --- OnTopic.Data.Sql/SqlDataReaderExtensions.cs | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs index 91ffef97..89fc5d9c 100644 --- a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs +++ b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs @@ -91,11 +91,13 @@ internal static class SqlDataReaderExtensions { var rawTopic = (ITopicBackingAccessor)addedTopic; - // HasExtendedAttribute is NULL when extended attributes are included - // HasExtendedAttribute is true when the blob wasn't loaded, but exists - if (reader.GetNullableBoolean("HasExtendedAttributes") is true) { - rawTopic.Attributes.LoadState = LoadState.NotLoaded; - } + // HasExtendedAttribute is NULL when extended attributes are included: Converge to Loaded, even on a pre-existing topic + // whose extended boundary was previously NotLoaded, and even if the topic has no extended attributes to read. + // HasExtendedAttribute is true when the blob wasn't loaded, but exists: Downgrade to NotLoaded, deferring the fetch. + // HasExtendedAttribute is false when the topic has no extended attributes at all: nothing to defer, so Loaded. + rawTopic.Attributes.LoadState = reader.GetNullableBoolean("HasExtendedAttributes") is true? + LoadState.NotLoaded : + LoadState.Loaded; // HasChildren is NULL when the column is not applicable (e.g., in version or update paths); skip those topics. // Pre-existing topics are excluded; their LoadState is already established, and they may have the lazy resolver wired up. From 47769ada7cc667fd8d62fb6a425e45516524d845 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 14 Jul 2026 19:19:45 -0700 Subject: [PATCH 171/337] Introduced the new `ConvergeLoadState()` method This lays the foundation to conditionally update the `LoadState` of a given collection property when loading a differential set of topics. E.g., if a `Load(isRecursive)` has a cached topic, but it or its children don't meet the full `TopicPayload`, we'll do another `Load()` and merge the results. The `ConvergeLoadState()` ensures that when that happens, we're updating the `LoadState` if it's (now) complete, leaving it be if it was a preexisting state (and thus outside the scope of this `Load()`), and otherwise set it to `NotLoaded` if it's a newly loaded topic. This lays the groundwork for filling a key gap in the lazy-loading (#111), which is a `Load()` hit on a cached topic that doesn't satisfy the contract of the new `Load()` signature. --- OnTopic.Data.Sql/SqlDataReaderExtensions.cs | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs index 89fc5d9c..d0813f5c 100644 --- a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs +++ b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs @@ -580,6 +580,24 @@ internal static void SetReferences(this IDataReader reader, TopicIndex topics, b } + /*============================================================================================================================ + | METHOD: CONVERGE LOAD STATE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Determines the converged for a boundary given whether this load fully provided it. + /// + /// + /// A load never downgrades a boundary it didn't fully provide. If , the boundary is promoted + /// to regardless of prior state. Otherwise, a pre-existing boundary is left untouched, + /// preserving whatever it already knew, while a freshly introduced boundary is set to , + /// deferring the fetch. + /// + /// The boundary's current . + /// Whether the topic was already resident in the topic index before this load began. + /// Whether this load fully provided the boundary. + private static LoadState ConvergeLoadState(LoadState current, bool isPreExisting, bool isComplete) => + isComplete? LoadState.Loaded : isPreExisting? current : LoadState.NotLoaded; + /*============================================================================================================================ | METHOD: SET VERSION HISTORY \---------------------------------------------------------------------------------------------------------------------------*/ From c998de191e4fe331250bd7ab6306ad5f6dc45833 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 14 Jul 2026 19:46:55 -0700 Subject: [PATCH 172/337] Applied `ConvergeLoadState()` to `AddChildTopic()` This applies the newly introduced `ConvergeLoadState()` (47769ada) to the `AddChildTopic()` method (0224cea1) for both extended attributes and children, with the former being based on the `HasExtendedAttributes` field (aa19e64a, 9475ec3e), while the latter is based on the `HasChildren` field (5b4bf6ba, e3e7cfba). This addresses the case where the `Children.TopicState` was `NotLoaded` and, thus, a `TopicPayload.Children` triggered on `EnsureLoaded()`, but the topic had at least one child already loaded, and thus e.g., its extended attributes or children may have been previously loaded, even if they're not loaded this round. Prior to this, these could get set to `NotLoaded` just because there were extended attributes or children that weren't loaded with this update, despite those previously having been loaded. This contributes to the lazy-loading project (#111) by accounting for cases where --- OnTopic.Data.Sql/SqlDataReaderExtensions.cs | 29 ++++++++++++++------- 1 file changed, 20 insertions(+), 9 deletions(-) diff --git a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs index d0813f5c..cce488cb 100644 --- a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs +++ b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs @@ -555,6 +555,9 @@ internal static void SetReferences(this IDataReader reader, TopicIndex topics, b /// The to populate. private static Topic? AddChildTopic(this IDataReader reader, Topic parent, TopicIndex topics) { + // Capture pre-existing status before AddTopic() introduces the topic to the index + var wasPreExisting = topics.ContainsKey(reader.GetTopicId()); + // Add or update the topic in the index var addedTopic = reader.AddTopic(topics, markDirty: false); @@ -565,15 +568,23 @@ internal static void SetReferences(this IDataReader reader, TopicIndex topics, b var rawTopic = (ITopicBackingAccessor)addedTopic; - // Set the extended-attribute load state based on the database hint - if (reader.GetNullableBoolean("HasExtendedAttributes") is true) { - rawTopic.Attributes.LoadState = LoadState.NotLoaded; - } - - // Set the children load state based on the database hint - rawTopic.Children.LoadState = reader.GetNullableBoolean("HasChildren") is true - ? LoadState.NotLoaded - : LoadState.Loaded; + // The extended attributes are completely loaded if HasExtendedAttributes is not true: NULL means this fill included + // extended attributes, and false means the child has none at all; either way, nothing is deferred. True means extended + // attributes exist but weren't requested this fill, deferring to lazy loading. + rawTopic.Attributes.LoadState = ConvergeLoadState( + rawTopic.Attributes.LoadState, + wasPreExisting, + isComplete: reader.GetNullableBoolean("HasExtendedAttributes") is not true + ); + + // The children property is completely loaded if HasChildren is not true. This fill only refreshes the child's own row, + // never its children, so a pre-existing child already Loaded from a prior Load() is preserved rather than downgraded; this + // fill returned no information about whether that boundary is complete + rawTopic.Children.LoadState = ConvergeLoadState( + rawTopic.Children.LoadState, + wasPreExisting, + isComplete: reader.GetNullableBoolean("HasChildren") is not true + ); // Return the topic created return addedTopic; From 9a7594a660eec869391bdf951d1cf66490f76bb8 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 14 Jul 2026 19:57:55 -0700 Subject: [PATCH 173/337] Apply `ConvergeLoadState()` to `LoadTopicGraph()` This applies the newly introduced `ConvergeLoadState()` (47769ada) to the `Load()` method for both extended attributes and children, with the former being based on the `HasExtendedAttributes` field (aa19e64a, 9475ec3e), while the latter is based on the `HasChildren` field (5b4bf6ba, e3e7cfba). This also relies on a new `preExistingIds` index to determine if this is a merge or a new topic. This lays the groundwork for addressing a key gap in the lazy-loading (#111), where a `Load()` hit on a cached topic that doesn't satisfy the contract of the new `Load()` signature. This ensures that a call to `LoadTopicGraph()` is capable of merging updated content into an existing topic while honoring the state based on the rules of `ConvergeLoadState()`. As part of this, I also refactored the logic for the initial `ReadAsync()` loop, such that it defines the `seedTopic` as part of that logic, uses `HasChildren` to set the initial `Children.LoadState`, then updates the `Children.LoadState` if any further topics after the `seedTopic` are loaded. This allows me to get rid of the previously introduced `hasChildrenMap` entirely, as well as the subsequent loop over both `ancestorIds` and `hasChildrenMap` to establish the `Children.LoadState`; this is much simpler! This contributes to the lazy-loading project (#111) by accounting for cases where --- OnTopic.Data.Sql/SqlDataReaderExtensions.cs | 75 ++++++++++----------- 1 file changed, 34 insertions(+), 41 deletions(-) diff --git a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs index cce488cb..bb8ecd69 100644 --- a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs +++ b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs @@ -74,8 +74,8 @@ internal static class SqlDataReaderExtensions { \-------------------------------------------------------------------------------------------------------------------------*/ var topics = referenceTopic is not null? referenceTopic.GetRootTopic().GetTopicIndex() : new(); var rootTopic = (Topic?)null; - HashSet preExistingIds = [..topics.Keys]; - var hasChildrenMap = new Dictionary(); + var preExistingIds = new HashSet(topics.Keys); + var seedTopic = (Topic?)null; /*-------------------------------------------------------------------------------------------------------------------------- | Populate topics @@ -85,51 +85,46 @@ internal static class SqlDataReaderExtensions { // Add the topic to the topic graph var addedTopic = reader.AddTopic(topics, markDirty); + var rawTopic = (ITopicBackingAccessor)addedTopic; - // The first topic returned is the root topic; store it for the return value + // The first topic returned is the root topic rootTopic ??= addedTopic; - var rawTopic = (ITopicBackingAccessor)addedTopic; + // If loading the entire tree, the rootTopic is also the seedTopic + if (seedTopicId < 0) { + seedTopic ??= addedTopic; + } - // HasExtendedAttribute is NULL when extended attributes are included: Converge to Loaded, even on a pre-existing topic - // whose extended boundary was previously NotLoaded, and even if the topic has no extended attributes to read. - // HasExtendedAttribute is true when the blob wasn't loaded, but exists: Downgrade to NotLoaded, deferring the fetch. - // HasExtendedAttribute is false when the topic has no extended attributes at all: nothing to defer, so Loaded. - rawTopic.Attributes.LoadState = reader.GetNullableBoolean("HasExtendedAttributes") is true? - LoadState.NotLoaded : - LoadState.Loaded; - - // HasChildren is NULL when the column is not applicable (e.g., in version or update paths); skip those topics. - // Pre-existing topics are excluded; their LoadState is already established, and they may have the lazy resolver wired up. - if (!preExistingIds.Contains(addedTopic.Id) && reader.GetNullableBoolean("HasChildren") is { } hasChildren) { - hasChildrenMap[addedTopic.Id] = hasChildren; + // Otherwise, check if the addedTopic is the seedTopic + else if (addedTopic.Id == seedTopicId) { + seedTopic = addedTopic; } - } + // The extended attributes are complete if HasExtendedAttributes is not true: NULL means extended attributes were included + // in this load, and false means the topic has no extended attributes at all; either way, nothing is deferred + var hasExtendedAttributes = reader.GetNullableBoolean("HasExtendedAttributes"); + rawTopic.Attributes.LoadState = ConvergeLoadState( + rawTopic.Attributes.LoadState, + preExistingIds.Contains(addedTopic.Id), + isComplete: hasExtendedAttributes is not true + ); - /*-------------------------------------------------------------------------------------------------------------------------- - | Stamp Children.LoadState - \-------------------------------------------------------------------------------------------------------------------------*/ - // Identifies the ancestor tree, stopping at the first pre-existing (i.e., not newly loaded) topic. Newly introduced - // ancestors have exactly one child loaded (from the ancestor crawl), but may have more; as such, they will be marked as - // NotLoaded. Note: An ancestor whose sole database child is part of the ancestor chain is still marked NotLoaded, since we - // don't have enough information to verify that. This is an unlikely scenario, but will cost one extra round-trip to verify. - HashSet ancestorIds = []; - if (topics.TryGetValue(seedTopicId, out var seedTopic)) { - var ancestor = seedTopic.Parent; - while (ancestor is not null && hasChildrenMap.ContainsKey(ancestor.Id)) { - ancestorIds.Add(ancestor.Id); - ancestor = ancestor.Parent; + // HasChildren is NULL when the column is not applicable (e.g., in version or update paths); skip those topics + // This applies to pre-existing topics too, since a differential load must be able to converge children LoadState as well + if (reader.GetNullableBoolean("HasChildren") is { } hasChildren) { + rawTopic.Children.LoadState = ConvergeLoadState( + rawTopic.Children.LoadState, + preExistingIds.Contains(addedTopic.Id), + isComplete: !hasChildren + ); + } + + // Any rows after the seed are a genuine child, indicating that the parent's full child set was returned. The parent may + // be unresolved (e.g., GetTopicUpdates' unordered, possibly-disconnected Refresh() batch), hence the null-conditional. + if (seedTopic is not null && addedTopic != seedTopic) { + (addedTopic.Parent as ITopicLazyLoadable)?.SetLoadState(TopicPayload.Children, LoadState.Loaded); } - } - // HasChildren NULL (i.e., absent from the map) means the topic was not newly loaded or the column is not applicable; - // either way, skip. Ancestors with children are NotLoaded (partial load); other topics check whether any children were - // loaded, implying that @HasChildren or @LoadDescendants was passed, and thus its children are fully loaded. - foreach (var (id, hasChildren) in hasChildrenMap) { - var topic = topics[id]; - var isNotLoaded = hasChildren && (ancestorIds.Contains(id) || topic.Children.Count == 0); - topic.Children.LoadState = isNotLoaded? LoadState.NotLoaded : LoadState.Loaded; } /*-------------------------------------------------------------------------------------------------------------------------- @@ -201,9 +196,7 @@ internal static class SqlDataReaderExtensions { /*-------------------------------------------------------------------------------------------------------------------------- | Return objects \-------------------------------------------------------------------------------------------------------------------------*/ - return seedTopicId >= 0 && topics.TryGetValue(seedTopicId, out var requestedTopic) - ? requestedTopic - : rootTopic; + return seedTopic; } From 86aaf98d996950c2b2fadaf0c5e33267a9c95421 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 14 Jul 2026 21:13:31 -0700 Subject: [PATCH 174/337] Introduced unit tests for `LoadTopicGraph()` Added unit tests that evaluate the relevant states, primarily around `LoadState`, around the refactoring of `LoadTopicGraph()` and, related, `FillChildren()`, both on the `SqlDataReaderExtensions` class, as enabled by the new `ConvergeLoadState()` method (47769ada, c998de19, 9a7594a6). This contributes to the testing of #111. --- OnTopic.Tests/SqlTopicRepositoryTest.cs | 272 ++++++++++++++++++++++++ 1 file changed, 272 insertions(+) diff --git a/OnTopic.Tests/SqlTopicRepositoryTest.cs b/OnTopic.Tests/SqlTopicRepositoryTest.cs index ddfbed18..15557446 100644 --- a/OnTopic.Tests/SqlTopicRepositoryTest.cs +++ b/OnTopic.Tests/SqlTopicRepositoryTest.cs @@ -7,8 +7,10 @@ using System.Text; using Microsoft.Data.SqlClient; using OnTopic.Associations; +using OnTopic.Collections.Specialized; using OnTopic.Data.Sql; using OnTopic.Data.Sql.Models; +using OnTopic.Querying; using OnTopic.Repositories; using OnTopic.Tests.Schemas; using Xunit; @@ -459,6 +461,202 @@ public async Task LoadTopicGraph_IndexedOnlyWithMissingReference_ReturnsNotLoade } + /*============================================================================================================================ + | TEST: LOAD TOPIC GRAPH: PRE-EXISTING WITH DEFERRED EXTENDED ATTRIBUTES: PRESERVES LOADED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Calls against a pre-existing, resident whose + /// is already , with a row indicating extended + /// attributes exist but weren't requested this load (HasExtendedAttributes = true), and confirms the resident is preserved rather than downgraded. + /// + /// + /// A load that doesn't request (e.g. a + /// top-up) must not silently discard the fact that the extended attribute property is already fully loaded; doing so would + /// trigger a needless refetch, and could clobber an unsaved local edit the next time it's touched. + /// + [Fact] + public async Task LoadTopicGraph_PreExistingWithDeferredExtendedAttributes_PreservesLoaded() { + + var topic = new Topic("Root", "Container", null, 1); + + using var topics = new TopicsDataTable(); + + topics.AddRow(1, "Root", "Container", hasExtendedAttributes: true); + + using var tableReader = new DataTableReader(topics); + + await tableReader.LoadTopicGraph(referenceTopic: topic, cancellationToken: CancellationToken); + + Assert.Equal(LoadState.Loaded, topic.Attributes.LoadState); + + } + + /*============================================================================================================================ + | TEST: LOAD TOPIC GRAPH: PRE-EXISTING SINGLE CHILD: PRESERVES LOADED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Calls against a pre-existing, resident that has + /// exactly one child, already fully , with a shallow reload of the seed that doesn't + /// re-return that child row, and confirms the resident is preserved, rather than downgraded. + /// + /// + /// Without this guard, a load's failure to re-return an already materialized single child (indistinguishable, by row count + /// alone, from a genuinely deferred boundary) would be misread as evidence the boundary was never loaded. + /// + [Fact] + public async Task LoadTopicGraph_PreExistingSingleChild_PreservesLoaded() { + + var topic = new Topic("Root", "Container", null, 1); + var child = new Topic("Child", "Page", topic, 2); + + ((ITopicBackingAccessor)topic).Children.LoadState = LoadState.Loaded; + + using var topics = new TopicsDataTable(); + + topics.AddRow(1, "Root", "Container", hasChildren: true); + + using var tableReader = new DataTableReader(topics); + + await tableReader.LoadTopicGraph(1, referenceTopic: topic, cancellationToken: CancellationToken); + + Assert.Equal(LoadState.Loaded, ((ITopicBackingAccessor)topic).Children.LoadState); + Assert.Equal(child, ((ITopicBackingAccessor)topic).Children.Single()); + + } + + /*============================================================================================================================ + | TEST: LOAD TOPIC GRAPH: PRE-EXISTING ANCESTOR: PRESERVES LOADED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Calls for a deep seed whose ancestor is preexisting and already + /// fully , and confirms the ancestor's is preserved rather + /// than downgraded by the ancestor crawl. + /// + /// + /// @LoadAscendants is passed for every + /// call outside of the root, regardless of isRecursive or payload, so the ancestor crawl runs on essentially every + /// load of anything beneath an already loaded ancestor. Without this guard, an already complete ancestor would be + /// perpetually reset to . + /// + [Fact] + public async Task LoadTopicGraph_PreExistingAncestor_PreservesLoaded() { + + var root = new Topic("Root", "Container", null, 1); + var ancestor = new Topic("Ancestor", "Container", root, 2); + var seed = new Topic("Seed", "Page", ancestor, 3); + + ((ITopicBackingAccessor)ancestor).Children.LoadState = LoadState.Loaded; + + using var topics = new TopicsDataTable(); + + topics.AddRow(1, "Root", "Container", hasChildren: true); + topics.AddRow(2, "Ancestor", "Container", 1, hasChildren: true); + topics.AddRow(3, "Seed", "Page", 2, hasChildren: false); + + using var tableReader = new DataTableReader(topics); + + await tableReader.LoadTopicGraph(3, referenceTopic: seed, cancellationToken: CancellationToken); + + Assert.Equal(LoadState.Loaded, ((ITopicBackingAccessor)ancestor).Children.LoadState); + + } + + /*============================================================================================================================ + | TEST: LOAD TOPIC GRAPH: FRESH ANCESTOR: SETS NOT LOADED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Calls for a deep seed whose ancestor has a sibling not returned by + /// this load, and confirms the freshly introduced ancestor's is still correctly set, + /// despite the seed's row naming the ancestor as its ParentID being processed after it. + /// + /// + /// Guards against a defect variant in the ancestor classification: If the seed's own row were allowed to credit its parent + /// as having received a "loaded" child, the ancestor would be incorrectly marked despite its + /// other child (the untouched sibling) having never been returned, thus risking DeleteUnmatched data loss on a + /// subsequent save. + /// + [Fact] + public async Task LoadTopicGraph_FreshAncestor_SetsNotLoaded() { + + using var topics = new TopicsDataTable(); + + topics.AddRow(1, "Root", "Container", hasChildren: true); + topics.AddRow(2, "Ancestor", "Container", 1, hasChildren: true); + topics.AddRow(3, "Seed", "Page", 2, hasChildren: false); + + using var tableReader = new DataTableReader(topics); + + var topic = await tableReader.LoadTopicGraph(3, cancellationToken: CancellationToken); + + Assert.NotNull(topic); + Assert.Equal(LoadState.NotLoaded, ((ITopicBackingAccessor)topic.Parent!).Children.LoadState); + + } + + /*============================================================================================================================ + | TEST: LOAD TOPIC GRAPH: DISCONNECTED BATCH: DOES NOT THROW + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Calls with a row whose ParentID names a topic that is + /// neither the first row nor otherwise resident, and confirms it completes without throwing. + /// + /// + /// Approximates the shape of GetTopicUpdates (used by ): An arbitrary, + /// possibly disconnected batch of individually modified topics, with HasChildren always NULL and no + /// guaranteed row order. A topic's parent may not be resolvable at all in that shape; must derive completeness from the raw ParentID column, never by navigating as an object, or this throws a . + /// + [Fact] + public async Task LoadTopicGraph_DisconnectedBatch_DoesNotThrow() { + + using var topics = new TopicsDataTable(); + + topics.AddRow(1, "Root", "Container"); + topics.AddRow(99, "Orphan", "Page", 999); + + using var tableReader = new DataTableReader(topics); + + var exception = await Record.ExceptionAsync( + async () => await tableReader.LoadTopicGraph(cancellationToken: CancellationToken) + ); + + Assert.Null(exception); + + } + + /*============================================================================================================================ + | TEST: LOAD TOPIC GRAPH: WHOLE TREE LOAD: CONVERGES NON-LEAF REGION NODES + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Calls with the default seedTopicId (-1, a whole-tree + /// load with no single seed) against a multi-level tree, and confirms a non-leaf node partway down the tree converges to + /// , rather than being misclassified as an ancestor. + /// + /// + /// The stored procedure resolves -1 to the actual root internally, so no returned row's id ever equals the literal + /// seedTopicId passed to ; the ancestor classification must not + /// mistake this for "no seed found yet" and misclassify the entire tree as ancestors. + /// + [Fact] + public async Task LoadTopicGraph_WholeTreeLoad_ConvergesNonLeafRegionNodes() { + + using var topics = new TopicsDataTable(); + + topics.AddRow(1, "Root", "Container", hasChildren: true); + topics.AddRow(2, "Branch", "Container", 1, hasChildren: true); + topics.AddRow(3, "Leaf", "Page", 2, hasChildren: false); + + using var tableReader = new DataTableReader(topics); + + var root = await tableReader.LoadTopicGraph(cancellationToken: CancellationToken); + var branch = root!.Children["Branch"]; + + Assert.Equal(LoadState.Loaded, ((ITopicBackingAccessor)branch).Children.LoadState); + + } + /*============================================================================================================================ | TEST: LOAD TOPIC GRAPH: WITH MISSING RELATIONSHIP: SETS NOT LOADED \---------------------------------------------------------------------------------------------------------------------------*/ @@ -737,6 +935,80 @@ public void TopicListDataTable_AddRow_Succeeds() { } + + /*============================================================================================================================ + | TEST: FILL CHILDREN: PRE-EXISTING CHILD WITHOUT EXTENDED ATTRIBUTES: CONVERGES LOADED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Calls for a pre-existing, resident child topic whose is , with a row indicating the topic genuinely has no + /// extended attributes (HasExtendedAttributes = false), and confirms the property converges to rather than being left stuck. + /// + /// + /// A children-only fill returns no extended attributes, but false is still definitive: There is nothing to defer, so + /// there's no reason to leave a pre-existing child's property until something else + /// happens to touch it. + /// + [Fact] + public async Task FillChildren_PreExistingChildWithoutExtendedAttributes_ConvergesLoaded() { + + var parent = new Topic("Parent", "Container", null, 1); + var child = new Topic("Child", "Page", parent, 2); + + ((ITopicBackingAccessor)child).Attributes.LoadState = LoadState.NotLoaded; + + using var topics = new TopicsDataTable(); + + topics.AddRow(1, "Parent", "Container", hasExtendedAttributes: false); + topics.AddRow(2, "Child", "Page", 1, hasExtendedAttributes: false); + + using var tableReader = new DataTableReader(topics); + + var topicIndex = parent.GetTopicIndex(); + + await tableReader.FillChildren(parent, topicIndex, CancellationToken); + + Assert.Equal(LoadState.Loaded, ((ITopicBackingAccessor)child).Attributes.LoadState); + + } + + /*============================================================================================================================ + | TEST: FILL CHILDREN: FRESH CHILD WITH EXTENDED ATTRIBUTES INCLUDED: CONVERGES LOADED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Calls for a fresh (not pre-existing) child topic with a row + /// indicating extended attributes were included with this fill (HasExtendedAttributes = NULL), and confirms the + /// boundary converges to rather than . + /// + /// + /// Reproduces being called + /// with TopicPayload.Children | TopicPayload.ExtendedAttributes: A single IncludeExtended parameter scopes + /// the whole GetTopics call, so children rows come back with HasExtendedAttributes = NULL, and their extended + /// attributes are delivered in the third result set, just like the seed's own row. + /// + [Fact] + public async Task FillChildren_FreshChildWithExtendedAttributesIncluded_ConvergesLoaded() { + + var parent = new Topic("Parent", "Container", null, 1); + + using var topics = new TopicsDataTable(); + + topics.AddRow(1, "Parent", "Container"); + topics.AddRow(2, "Child", "Page", 1); + + using var tableReader = new DataTableReader(topics); + + var topicIndex = parent.GetTopicIndex(); + + await tableReader.FillChildren(parent, topicIndex, CancellationToken); + + var child = (ITopicBackingAccessor)topicIndex[2]; + + Assert.Equal(LoadState.Loaded, child.Attributes.LoadState); + + } + /*============================================================================================================================ | TEST: ATTRIBUTE VALUES DATA TABLE: ADD ROW: SUCCEEDS \---------------------------------------------------------------------------------------------------------------------------*/ From 5da119021858769ede9c8073c0c997b6314dadf3 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 14 Jul 2026 21:31:44 -0700 Subject: [PATCH 175/337] Support `Load(TopicPayload.Children)` MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Previously, the `SqlTopicRepository` didn't support returning children when `Load()` was called with `TopicPayload.Children`; this could only be done by either a) calling `isRecursive` (which returns _all_ children), or by b) relying on `EnsureLoaded()`. While this was by design, there's no reason not to also support `TopicPayload.Children` in `Load()`. This is also potentially useful for cases where we want e.g., a topic and all nested topics, which would require its children to be loaded. Given other foundational work that's been committed, all this requires is adding the `@LoadChildren` parameter to the `GetTopics` stored procedure—handy! This fills a gap in the lazy-loading plan (#111) related to partial loads. --- OnTopic.Data.Sql/SqlTopicRepository.cs | 1 + 1 file changed, 1 insertion(+) diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index b75cdf84..47f44bea 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -141,6 +141,7 @@ public SqlTopicRepository(string connectionString) { \-------------------------------------------------------------------------------------------------------------------------*/ command.AddParameter("TopicID", topicId); command.AddParameter("LoadDescendants", isRecursive); + command.AddParameter("LoadChildren", payload.HasFlag(TopicPayload.Children) && !isRecursive); command.AddParameter("LoadAscendants", topicId >= 0); command.AddParameter("IncludeExtended", payload.HasFlag(TopicPayload.ExtendedAttributes)); command.AddParameter("IncludeRelationships", true); From f247c2353178ca1835b9205d6947be2c232f23fc Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 14 Jul 2026 21:40:41 -0700 Subject: [PATCH 176/337] Add unit test for `Load(TopicPayload.Children)` This adds a unit test to verify that the newly introduced support for calling `SqlTopicRepository.Load()` with `TopicPayload.Children` works as expected. This contributes to the testing of #111. --- OnTopic.Tests/SqlTopicRepositoryTest.cs | 27 +++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/OnTopic.Tests/SqlTopicRepositoryTest.cs b/OnTopic.Tests/SqlTopicRepositoryTest.cs index 15557446..28c37fca 100644 --- a/OnTopic.Tests/SqlTopicRepositoryTest.cs +++ b/OnTopic.Tests/SqlTopicRepositoryTest.cs @@ -912,6 +912,33 @@ public async Task LoadTopicGraph_WithHasChildrenOnAncestorAndLoadedSubtree_SetsL } + /*============================================================================================================================ + | TEST: LOAD TOPIC GRAPH: WITH ONE LEVEL OF CHILDREN: CONVERGES SEED, LEAVES GRANDCHILDREN NOT LOADED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Calls with a result set shaped like a non-recursive + /// @LoadChildren call, with the seed's immediate child present, but that child's own children are not, and confirms the + /// seed converges to while the child (which received no rows of its own) remains . + /// + [Fact] + public async Task LoadTopicGraph_WithOneLevelOfChildren_ConvergesSeedLeavesGrandchildrenNotLoaded() { + + using var topics = new TopicsDataTable(); + + topics.AddRow(1, "Root", "Container", hasChildren: true); + topics.AddRow(2, "Child", "Container", 1, hasChildren: true); + + using var tableReader = new DataTableReader(topics); + + var seedTopic = await tableReader.LoadTopicGraph(1, cancellationToken: CancellationToken); + var childTopic = ((ITopicBackingAccessor?)seedTopic)?.Children.FirstOrDefault(); + + Assert.Equal(LoadState.Loaded, ((ITopicBackingAccessor?)seedTopic)?.Children.LoadState); + Assert.Equal(LoadState.NotLoaded, ((ITopicBackingAccessor?)childTopic)?.Children.LoadState); + + } + /*============================================================================================================================ | TEST: TOPIC LIST DATA TABLE: ADD ROW: SUCCEEDS \---------------------------------------------------------------------------------------------------------------------------*/ From b339d610c01d978744f95d8e40002e76c56f75de Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 14 Jul 2026 22:02:05 -0700 Subject: [PATCH 177/337] Support `Topic.IsLoaded(..., isRecursive)` We already support `Topic.IsLoaded(TopicPayload)` (e5ddc262) or, rather, `ITopicLazyLoadable.IsLoaded(TopicPayload)` via a default interface member (e66cea7f). This introduces support for `Topic.IsLoaded(TopicPayload, isRecursive)` via the `TopicExtensions`. This extends the implementation of `IsLoaded()` as called for by #111. --- OnTopic/Repositories/ITopicLazyLoadable.cs | 46 ++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/OnTopic/Repositories/ITopicLazyLoadable.cs b/OnTopic/Repositories/ITopicLazyLoadable.cs index b1007a5a..208ba5f7 100644 --- a/OnTopic/Repositories/ITopicLazyLoadable.cs +++ b/OnTopic/Repositories/ITopicLazyLoadable.cs @@ -64,6 +64,52 @@ bool IsLoaded(TopicPayload payload) { } + /*============================================================================================================================ + | METHOD: IS LOADED (RECURSIVE) + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Returns if every property flag in has already been fetched from the + /// underlying persistence store and, if , the same is true of every descendant. + /// + /// + /// Recursion is gated on being fully before + /// descending, so an unloaded branch is never mistaken for a loaded, empty one. Like , + /// this only ever reads values, never an autoloading getter, so it is safe to use for cases that + /// should not trigger a lazy load. + /// + /// One or more flags to test. + /// + /// Determines whether descendants should also be evaluated against . + /// + bool IsLoaded(TopicPayload payload, bool isRecursive) { + + // Evaluate current topic + if (!IsLoaded(payload)) { + return false; + } + + // Return if non-recursive + if (!isRecursive) { + return true; + } + + // Evaluate children, without triggering a load + if (!IsLoaded(TopicPayload.Children)) { + return false; + } + + // Recurse over children + foreach (var child in Children) { + if (!((ITopicLazyLoadable)child).IsLoaded(payload, isRecursive: true)) { + return false; + } + } + + // Return result + return true; + + } + /*============================================================================================================================ | METHOD: SET LOAD STATE \---------------------------------------------------------------------------------------------------------------------------*/ From 8893273df7611b7125b1baa8eed33109925d6bc0 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 14 Jul 2026 22:13:33 -0700 Subject: [PATCH 178/337] Established tests for `IsLoaded(..., isRecursive)` This establishes unit tests for the newly introduced `IsLoaded(TopicPayload, isRecursive)` overload on the `ITopicLazyLoadable` interface. As part of this, I also established a new `ITopicLazyLoadableTest` class for testing these methods. In a future commit, I'll migrate other test cases over here. This contributes to the testing for #111. --- OnTopic.Tests/ITopicLazyLoadableTest.cs | 153 ++++++++++++++++++++++++ 1 file changed, 153 insertions(+) create mode 100644 OnTopic.Tests/ITopicLazyLoadableTest.cs diff --git a/OnTopic.Tests/ITopicLazyLoadableTest.cs b/OnTopic.Tests/ITopicLazyLoadableTest.cs new file mode 100644 index 00000000..c176bdd9 --- /dev/null +++ b/OnTopic.Tests/ITopicLazyLoadableTest.cs @@ -0,0 +1,153 @@ +/*============================================================================================================================== +| Author Ignia, LLC +| Client Ignia, LLC +| Project Topics Library +\=============================================================================================================================*/ +using OnTopic.Repositories; +using OnTopic.Tests.TestDoubles; +using Xunit; + +namespace OnTopic.Tests; + +/*============================================================================================================================== +| CLASS: TOPIC LAZY LOADABLE TEST +\-----------------------------------------------------------------------------------------------------------------------------*/ +/// +/// Provides unit tests for the interface, with a particular emphasis on the recursive overload. +/// +[ExcludeFromCodeCoverage] +public class ITopicLazyLoadableTest { + + /*============================================================================================================================ + | TEST: IS LOADED: NON-RECURSIVE: IGNORES UNLOADED CHILDREN + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Creates a topic with fully loaded extended attributes but a children collection. + /// Verifies that a non-recursive query returns true + /// once the requested payload is satisfied, regardless of the state of . + /// + [Fact] + public void IsLoaded_NonRecursive_IgnoresUnloadedChildren() { + + var topic = (ITopicLazyLoadable)new Topic("Test", "Page", null, 1) { + Children = { + LoadState = LoadState.NotLoaded + } + }; + + var result = topic.IsLoaded(TopicPayload.ExtendedAttributes, isRecursive: false); + + Assert.True(result); + + } + + /*============================================================================================================================ + | TEST: IS LOADED: SHALLOW SEED: RECURSIVE RETURNS FALSE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Creates a topic with a single, unloaded child collection. Verifies that returns false for a recursive query, since the seed's are not yet loaded. + /// + [Fact] + public void IsLoaded_ShallowSeed_Recursive_ReturnsFalse() { + + var topic = (ITopicLazyLoadable)new Topic("Test", "Page", null, 1) { + Children = { + LoadState = LoadState.NotLoaded + } + }; + + Assert.False(topic.IsLoaded(TopicPayload.All, isRecursive: true)); + + } + + /*============================================================================================================================ + | TEST: IS LOADED: FULLY RESIDENT SUBTREE: RECURSIVE RETURNS TRUE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Creates a three-level topic hierarchy with every collection fully loaded. Verifies that returns true once the whole subtree is loaded. + /// + [Fact] + public void IsLoaded_FullyResidentSubtree_Recursive_ReturnsTrue() { + + var parent = new Topic("Parent", "Page", null, 1); + var child = new Topic("Child", "Page", parent, 2); + _ = new Topic("Grandchild", "Page", child, 3); + + Assert.True(((ITopicLazyLoadable)parent).IsLoaded(TopicPayload.All, isRecursive: true)); + + } + + /*============================================================================================================================ + | TEST: IS LOADED: NOT LOADED DESCENDANT: RECURSIVE RETURNS FALSE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Creates a three-level topic hierarchy where the middle topic's extended attributes are . Verifies that returns + /// false for a recursive query, even though the seed and its collection are fully + /// loaded. + /// + [Fact] + public void IsLoaded_NotLoadedDescendant_Recursive_ReturnsFalse() { + + var parent = new Topic("Parent", "Page", null, 1); + var child = new Topic("Child", "Page", parent, 2); + _ = new Topic("Grandchild", "Page", child, 3); + + child.Attributes.LoadState = LoadState.NotLoaded; + + Assert.False(((ITopicLazyLoadable)parent).IsLoaded(TopicPayload.ExtendedAttributes, isRecursive: true)); + + } + + /*============================================================================================================================ + | TEST: IS LOADED: NOT LOADED CHILDREN: EXCLUDED PAYLOAD: RECURSIVE RETURNS FALSE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Creates a two-level topic hierarchy where the seed's collection is , and queries a payload parameter that excludes . + /// Verifies that still returns false, confirming + /// that the children gate is evaluated independently of the requested payload before recursing. + /// + [Fact] + public void IsLoaded_NotLoadedChildren_ExcludedPayload_Recursive_ReturnsFalse() { + + var parent = new Topic("Parent", "Page", null, 1); + _ = new Topic("Child", "Page", parent, 2); + + parent.Children.LoadState = LoadState.NotLoaded; + + var result = ((ITopicLazyLoadable)parent).IsLoaded(TopicPayload.ExtendedAttributes, isRecursive: true); + + Assert.False(result); + + } + + /*============================================================================================================================ + | TEST: IS LOADED: NOT LOADED CHILDREN: NEVER TRIGGERS A LOAD + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Creates a topic stamped with a and a children + /// collection. Verifies that reads + /// directly and returns false without triggering a lazy load of . + /// + [Fact] + public void IsLoaded_NotLoadedChildren_NeverTriggersLoad() { + + var topic = new Topic("Test", "Page", null, 1); + var loader = new TrackingTopicLazyLoader(); + + ((ITopicLazyLoadable)topic).Loader = loader; + topic.Children.LoadState = LoadState.NotLoaded; + + var result = ((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.All, isRecursive: true); + + Assert.False(result); + Assert.False(loader.WasCalled); + + } + +} //Class \ No newline at end of file From d578cbf39b11240c1276bbdea37d4b1c8fd951d2 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 14 Jul 2026 22:30:57 -0700 Subject: [PATCH 179/337] Relocated tests to `ITopicLazyLoadableTest` With the introduction of `ITopicLazyLoadableTest` (8893273d), some tests that are specific to `ITopicLazyLoadable`, but were placed on other tests before `ITopicLazyLoadableTest` was introduced, can be moved to this more appropriate home. (In fairness, these may have predated `ITopicLazyLoadable` as well, and not just its test class.) This contributes to the testing of the lazy-loading framework (#111). --- OnTopic.Tests/ITopicLazyLoadableTest.cs | 31 ++++++++++++++++++++++++ OnTopic.Tests/TopicTest.cs | 32 ------------------------- 2 files changed, 31 insertions(+), 32 deletions(-) diff --git a/OnTopic.Tests/ITopicLazyLoadableTest.cs b/OnTopic.Tests/ITopicLazyLoadableTest.cs index c176bdd9..103f6e45 100644 --- a/OnTopic.Tests/ITopicLazyLoadableTest.cs +++ b/OnTopic.Tests/ITopicLazyLoadableTest.cs @@ -150,4 +150,35 @@ public void IsLoaded_NotLoadedChildren_NeverTriggersLoad() { } + /*============================================================================================================================ + | TEST: ENSURE LOADED: NULL RESOLVER: DOES NOT THROW + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Calls on an in-memory topic with no + /// loader and confirms it completes without throwing. + /// + [Fact] + public void EnsureLoaded_NullResolver_DoesNotThrow() { + var topic = new Topic("Topic", "Page"); + ((ITopicLazyLoadable)topic).EnsureLoaded(TopicPayload.All); + } + + /*============================================================================================================================ + | TEST: IS NEW: NEW TOPIC: HAS NULL LOADER + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Confirms that a newly constructed, unsaved carries a null . + /// + /// + /// Ensures that only stamps + /// once a topic has been loaded or saved (and thus has a stable ), so an in-memory, unsaved topic can + /// never carry one. + /// + [Fact] + public void IsNew_NewTopic_HasNullLoader() { + var topic = new Topic("Topic", "Page"); // ID = -1, IsNew = true + Assert.True(topic.IsNew); + Assert.Null(((ITopicLazyLoadable)topic).Loader); + } + } //Class \ No newline at end of file diff --git a/OnTopic.Tests/TopicTest.cs b/OnTopic.Tests/TopicTest.cs index b562b35c..53ad8f3e 100644 --- a/OnTopic.Tests/TopicTest.cs +++ b/OnTopic.Tests/TopicTest.cs @@ -5,7 +5,6 @@ \=============================================================================================================================*/ using OnTopic.Collections; using OnTopic.Metadata; -using OnTopic.Repositories; using Xunit; namespace OnTopic.Tests; @@ -455,35 +454,4 @@ public void MarkClean_NewTopic_RemainsDirty() { } - /*============================================================================================================================ - | TEST: ENSURE LOADED: NULL RESOLVER: DOES NOT THROW - \---------------------------------------------------------------------------------------------------------------------------*/ - /// - /// Calls on an in-memory topic with no - /// loader and confirms it completes without throwing. - /// - [Fact] - public void EnsureLoaded_NullResolver_DoesNotThrow() { - var topic = new Topic("Topic", "Page"); - ((ITopicLazyLoadable)topic).EnsureLoaded(TopicPayload.All); - } - - /*============================================================================================================================ - | TEST: IS NEW: NEW TOPIC: HAS NULL LOADER - \---------------------------------------------------------------------------------------------------------------------------*/ - /// - /// Confirms that a newly constructed, unsaved carries a null . - /// - /// - /// Ensures that only stamps - /// once a topic has been loaded or saved (and thus has a stable ), so an in-memory, unsaved topic can - /// never carry one. - /// - [Fact] - public void IsNew_NewTopic_HasNullLoader() { - var topic = new Topic("Topic", "Page"); // ID = -1, IsNew = true - Assert.True(topic.IsNew); - Assert.Null(((ITopicLazyLoadable)topic).Loader); - } - } //Class \ No newline at end of file From 167067f3241f2ef3f73773752435df0cd03bd43b Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Wed, 15 Jul 2026 17:01:36 -0700 Subject: [PATCH 180/337] Introduced `ResolveAssociations()` This complements `ResolveDeferredAssociations()` by connecting relationships and references to any in-memory references, but without looking up missing references via `Load()`. This achieves this by centralizing the code between this and `ResolveDeferredAssociations()` in a new `ResolveAssociations()` overload that accepts the `fallBackToLoad` parameter to determine if it should call `Load()` if the topic can't be found in the in-memory graph, or just keep the association deferred. This relates to the lazy-loading implementation (#111). --- .../LazyLoadingTopicRepository.cs | 105 +++++++++++++++--- 1 file changed, 88 insertions(+), 17 deletions(-) diff --git a/OnTopic/Repositories/LazyLoadingTopicRepository.cs b/OnTopic/Repositories/LazyLoadingTopicRepository.cs index 3ad686c7..441941bc 100644 --- a/OnTopic/Repositories/LazyLoadingTopicRepository.cs +++ b/OnTopic/Repositories/LazyLoadingTopicRepository.cs @@ -4,6 +4,7 @@ | Project Topics Library \=============================================================================================================================*/ using OnTopic.Associations; +using OnTopic.Querying; namespace OnTopic.Repositories; @@ -70,13 +71,15 @@ protected override void OnTopicSaved(TopicSaveEventArgs args) { | METHOD: LOAD DEFERRED ASSOCIATIONS \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Resolves any relationship and reference targets that were deferred when loading each through this repository's own - /// . + /// Resolves any relationships and references that were deferred when loaded through this repository's , preferring whatever is already available in the topic's + /// graph before falling back to a fresh for any + /// that aren't. /// /// - /// Targets that cannot be found after this are treated as stale references to deleted topics; this completed by clearing - /// the , resulting in the corresponding association collection to . + /// Targets that cannot be found after this are treated as stale references to deleted topics; this is completed by clearing + /// the , resulting in the corresponding collection's becoming . /// /// The topic whose deferred associations should be resolved. /// @@ -84,36 +87,104 @@ protected override void OnTopicSaved(TopicSaveEventArgs args) { /// "TopicPayload.References"/> are acted upon. /// /// An optional token that can be used to cancel the operation. - protected async Task LoadDeferredAssociations(Topic topic, TopicPayload payload, CancellationToken cancellationToken) { + protected Task LoadDeferredAssociations(Topic topic, TopicPayload payload, CancellationToken cancellationToken) { + Contract.Requires(topic, nameof(topic)); + return ResolveAssociations(topic, payload, fallBackToLoad: true); + } - // Validate input + /*============================================================================================================================ + | METHOD: RESOLVE ASSOCIATIONS + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Resolves any relationship and reference targets that are already present in the 's graph, + /// without triggering a load for targets that aren't. + /// + /// + /// The counterpart to , exposed so a merge + /// that brings new descendants into a resident graph can cheaply reconnect whatever has become resolvable, without + /// discarding what's still genuinely absent, or triggering a potentially expensive roundtrip to the persistence store. + /// + /// The topic whose deferred associations should be resolved against the resident graph. + /// + /// The payload flags that were requested; only and are acted upon. + /// + protected Task ResolveAssociations(Topic topic, TopicPayload payload) { Contract.Requires(topic, nameof(topic)); + return ResolveAssociations(topic, payload, fallBackToLoad: false); + } + + /// + /// Resolves each deferred relationship and reference entry on against its resident graph, + /// optionally falling back to for whatever the + /// graph doesn't have. + /// + /// + /// The shared core behind both ( : unresolvable targets are treated as stale and discarded) and ( : a + /// miss is left deferred for a later fallback); the two differ only in that flag. + /// + /// The topic whose deferred associations should be resolved. + /// + /// The payload flags that were requested; only and are acted upon. + /// + /// + /// Whether an association missing from the graph should be fetched via , with whatever remains unresolved afterwards cleared as + /// stale. + /// + private async Task ResolveAssociations(Topic topic, TopicPayload payload, bool fallBackToLoad) { + + // Narrow to the associations that remain deferred, skipping the graph lookup entirely if neither is + payload &= TopicPayload.Relationships | TopicPayload.References; + payload = ((ITopicLazyLoadable)topic).FilterPayload(payload); + + if (payload is TopicPayload.None) { + return; + } // Cast topic to safely access backing fields var rawTopic = (ITopicBackingAccessor)topic; - // Resolve deferred relationship targets; unresolvable targets are treated as stale and discarded + // Index the resident graph by id + var topicIndex = topic.GetRootTopic().GetTopicIndex(); + + // Resolve deferred relationship targets if (payload.HasFlag(TopicPayload.Relationships)) { foreach (var deferred in rawTopic.Relationships.Deferred.ToArray()) { - var target = await Load(deferred.TopicId).ConfigureAwait(false); - // SetValue removes the matching Deferred entry; any left unresolved are cleared below - if (target is not null) { + // SetValue removes the matching Deferred entry; any left unresolved are optionally cleared below + if (await resolveTarget(deferred.TopicId).ConfigureAwait(false) is { } target) { rawTopic.Relationships.SetValue(deferred.Key, target, markDirty: false); } } - rawTopic.Relationships.Deferred.Clear(); + if (fallBackToLoad) { + rawTopic.Relationships.Deferred.Clear(); + } } - // Resolve deferred reference targets; unresolvable targets are treated as stale and discarded + // Resolve deferred reference targets if (payload.HasFlag(TopicPayload.References)) { foreach (var deferred in rawTopic.References.Deferred.ToArray()) { - var target = await Load(deferred.TopicId).ConfigureAwait(false); - // SetValue removes the matching Deferred entry; any left unresolved are cleared below - if (target is not null) { + // SetValue removes the matching Deferred entry; any left unresolved are optionally cleared below + if (await resolveTarget(deferred.TopicId).ConfigureAwait(false) is { } target) { rawTopic.References.SetValue(deferred.Key, target, markDirty: false); } } - rawTopic.References.Deferred.Clear(); + if (fallBackToLoad) { + rawTopic.References.Deferred.Clear(); + } + } + + return; + + // Resolves a deferred entry against the index, falling back to Load() only when requested and only on a miss + async Task resolveTarget(int targetId) { + if (topicIndex.TryGetValue(targetId, out var target)) { + return target; + } + return fallBackToLoad ? await Load(targetId).ConfigureAwait(false) : null; } } From 4037de9ce1a6e058c6e1b6f13485a17fc23e13a3 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Wed, 15 Jul 2026 17:09:36 -0700 Subject: [PATCH 181/337] Filter out `IsNew` in `TopicIndex` The entire point of `TopicIndex` is to provide an index of `Topic.Id` for quick lookup. If a Topic `IsNew` then it's `Topic.Id` is `-1`. That's not only not useful, but will create a runtime exception due to the duplicate key if more than one new topic is in the graph. As a result, filter these out. --- OnTopic/Collections/Specialized/TopicIndex.cs | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/OnTopic/Collections/Specialized/TopicIndex.cs b/OnTopic/Collections/Specialized/TopicIndex.cs index 0b0a49c8..34e1bb9b 100644 --- a/OnTopic/Collections/Specialized/TopicIndex.cs +++ b/OnTopic/Collections/Specialized/TopicIndex.cs @@ -21,9 +21,17 @@ public class TopicIndex : Dictionary { /// Initializes a new instance of the . /// /// Seeds the collection with an optional list of topic references. + /// + /// Unsaved instances () are skipped, since their is a + /// placeholder shared by every other unsaved topic, not a real identity, and so isn't a genuine collision. Any other + /// colliding reflects corrupt data and continues to throw. + /// public TopicIndex(IEnumerable? topics = null) { if (topics is not null) { - foreach(var topic in topics) { + foreach (var topic in topics) { + if (topic.IsNew) { + continue; + } Add(topic.Id, topic); } } From 4f11cf8f758a8b9e9f91ddaded3a2f2b577530a0 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Wed, 15 Jul 2026 17:36:09 -0700 Subject: [PATCH 182/337] Fixed offset to avoid collisions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The original zero-based ID assignments inadvertently resulted in overlapping IDs, since 00000 resolves to 0, which resulted in invalid test data—and exceptions when indexing via `GetTopicIndex()`. I've fixed this by starting IDs at 1, instead of 0, so 00000 becomes 11111. This also meant having to adjust each of our test cases to reflect this. Technically, this is a packaged test double, so this will need to be documented as a breaking change. --- OnTopic.TestDoubles/StubTopicRepository.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/OnTopic.TestDoubles/StubTopicRepository.cs b/OnTopic.TestDoubles/StubTopicRepository.cs index 90ac0c36..2015eb05 100644 --- a/OnTopic.TestDoubles/StubTopicRepository.cs +++ b/OnTopic.TestDoubles/StubTopicRepository.cs @@ -393,7 +393,7 @@ AttributeDescriptor addAttribute( /// Creates a collection of fake data recursively based on a parent topic, and set number of levels. /// private static void CreateFakeData(Topic parent, int count = 3, int depth = 3) { - for (var i = 0; i < count; i++) { + for (var i = 1; i <= count; i++) { var topic = new Topic(parent.Key + "_" + i, "Page", parent, parent.Id + (int)Math.Pow(10, depth) * i); topic.Attributes.SetValue("ParentKey", parent.Key); topic.Attributes.SetValue("DepthCount", (depth+i).ToString(CultureInfo.InvariantCulture)); From 012c37c1bfbcccb0e694fc242e185ef5bff531bd Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Thu, 16 Jul 2026 16:51:47 -0700 Subject: [PATCH 183/337] =?UTF-8?q?Introduce=20`EnsureLoaded(=E2=80=A6,=20?= =?UTF-8?q?isRecursive)`=20overload?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Unlike the other versions of `EnsureLoaded()`, which are called via the `ILazyLoadable` interface on `Topic`, this is called from the `CachedTopicRepository.Load()` itself, and it ensures that an already loaded `Topic` is properly satisfies the requirements of the `TopicPayload`, potentially including `isRecursive`. Underneath, if it's `isRecursive`, and the payload isn't satisfied, it reruns the entire query from the underlying `TopicRepository` and merges the results into the topic graph using the newly introduced `ConvergeLoadState()` (47769ada, c998de19, 9a7594a6). Otherwise it defers to the normal `EnsureLoaded()` for that single topic. This finalizes the resolution of a major gap in the initial lazy-loading implementation (#111). --- OnTopic.Data.Caching/CachedTopicRepository.cs | 113 +++++++++++++++--- 1 file changed, 94 insertions(+), 19 deletions(-) diff --git a/OnTopic.Data.Caching/CachedTopicRepository.cs b/OnTopic.Data.Caching/CachedTopicRepository.cs index 27000ab9..960ee247 100644 --- a/OnTopic.Data.Caching/CachedTopicRepository.cs +++ b/OnTopic.Data.Caching/CachedTopicRepository.cs @@ -86,10 +86,11 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos \---------------------------------------------------------------------------------------------------------------------------*/ /// /// - /// Returns the cached topic if present. On a miss, falls through to the underlying repository with @LoadAscendants - /// enabled so the full ancestor chain is fetched and merged into the live graph. - /// Missing IDs are recorded to prevent - /// redundant round-trips for topics that genuinely do not exist. + /// Returns a cached topic if it satisfies the requested and ; an + /// insufficient hit is topped up via before being returned. On a + /// miss, falls through to the underlying repository with @LoadAscendants enabled so the full ancestor chain is + /// fetched and merged into the live graph. Missing IDs are recorded to prevent redundant round-trips for topics that + /// genuinely do not exist. /// public override async Task Load( int topicId, @@ -102,16 +103,20 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos | Handle request for entire tree \-------------------------------------------------------------------------------------------------------------------------*/ if (topicId < 0) { + await EnsureLoaded(_cache, payload, isRecursive).ConfigureAwait(false); return _cache; } /*-------------------------------------------------------------------------------------------------------------------------- - | Lookup by topic identifier; return immediately on a hit + | Lookup by topic identifier; top up and return on a hit \-------------------------------------------------------------------------------------------------------------------------*/ + Topic? topic; lock (_syncLock) { - if (_topicIdIndex.TryGetValue(topicId, out var topic)) { - return topic; - } + _topicIdIndex.TryGetValue(topicId, out topic); + } + if (topic is not null) { + await EnsureLoaded(topic, payload, isRecursive).ConfigureAwait(false); + return topic; } /*-------------------------------------------------------------------------------------------------------------------------- @@ -151,10 +156,11 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos /// /// - /// Returns the cached topic if present. On a miss, falls through to the underlying repository with @LoadAscendants - /// enabled so the full ancestor chain is fetched and merged into the live graph. - /// Missing IDs are recorded to prevent - /// redundant round-trips for topics that genuinely do not exist. + /// Returns a cached topic if it satisfies the requested and ; an + /// insufficient hit is topped up via before being returned. On a + /// miss, falls through to the underlying repository with @LoadAscendants enabled so the full ancestor chain is + /// fetched and merged into the live graph. Missing IDs are recorded to prevent redundant round-trips for topics that + /// genuinely do not exist. /// public override async Task Load( string uniqueKey, @@ -181,12 +187,15 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos } /*-------------------------------------------------------------------------------------------------------------------------- - | Lookup by unique key; return immediately on a hit + | Lookup by unique key; top up and return on a hit \-------------------------------------------------------------------------------------------------------------------------*/ + Topic? resident; lock (_syncLock) { - if (_topicKeyIndex.TryGetValue(uniqueKey, out var topic)) { - return topic; - } + _topicKeyIndex.TryGetValue(uniqueKey, out resident); + } + if (resident is not null) { + await EnsureLoaded(resident, payload, isRecursive).ConfigureAwait(false); + return resident; } /*-------------------------------------------------------------------------------------------------------------------------- @@ -288,8 +297,6 @@ public virtual async Task EnsureLoaded(Topic topic, TopicPayload payload, Cancel \-------------------------------------------------------------------------------------------------------------------------*/ await LoadDeferredAssociations(topic, payload, cancellationToken).ConfigureAwait(false); - // Update flat index for any newly loaded children - } /*============================================================================================================================ @@ -418,8 +425,9 @@ protected override void OnTopicRenamed(TopicRenameEventArgs args) { } /*============================================================================================================================ - | METHODS: PRIVATE + | METHOD: REKEY TOPIC SUBTREE \---------------------------------------------------------------------------------------------------------------------------*/ + /// /// Removes stale _topicByKey entries for and its descendants by swapping the prefix for the current one, then reindexes the subtree under its current unique keys. @@ -456,6 +464,73 @@ private void IndexTopic(Topic topic) { _topicKeyIndex[topic.GetUniqueKey()] = topic; } + /*============================================================================================================================ + | METHOD: ENSURE LOADED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Confirms that already satisfies the requested and scope and, if not, tops it up in place; the caller's own reference to reflects + /// whatever is added. + /// + /// + /// + /// Relationships and references are excluded from the sufficiency gate since Load() never guarantees a fully + /// resolved target graph, so gating on them would prevent convergence and force a reload on every hit. + /// + /// + /// A single-topic shortfall is topped up via , which converges LoadState in a single batched round-trip. A recursive shortfall, including a whole-tree + /// request, performs one deep against the + /// underlying repository—using itself as the reference topic, since it is already resident in, + /// and thus already a valid handle into, the live graph—merges the result into the live graph via , and then looks up any in-graph associations (), so any relationship or reference targets + /// that just became resident are connected without a further trip. + /// + /// + /// The already-resident topic to confirm or top up. + /// The flags the caller requires to be loaded. + /// Whether the caller requires the full subtree, not merely itself. + private async Task EnsureLoaded( + Topic topic, + TopicPayload payload, + bool isRecursive + ) { + + // Narrow the sufficiency gate to exclude relationships and references, which Load() never guarantees are fully resolved + var gate = payload & ~(TopicPayload.Relationships | TopicPayload.References); + + // Return immediately if the resident topic already satisfies the requested scope + if (((ITopicLazyLoadable)topic).IsLoaded(gate, isRecursive)) { + return; + } + + // Top up a non-recursive shortfall via the loader, which converges LoadState in a single round-trip + if (!isRecursive) { + await ((ITopicLazyLoadable)topic).EnsureLoaded(gate).ConfigureAwait(false); + return; + } + + // Top up a recursive shortfall via one deep load, merged into the live graph + var loaded = await TopicRepository + .Load(topic.Id, topic, isRecursive, payload) + .ConfigureAwait(false); + + if (loaded is not null) { + + // Rewire the returned ancestor chain onto the existing cache objects + MergeIntoCache(loaded); + + // Opportunistically connect any relationship or reference targets that are now resident in the merged region, regardless + // of whether relationships or references were themselves part of the requested payload + foreach (var descendant in loaded.FindAll()) { + await ResolveAssociations(descendant, TopicPayload.Relationships | TopicPayload.References).ConfigureAwait(false); + } + + } + + } + /*============================================================================================================================ | METHOD: MERGE INTO CACHE \---------------------------------------------------------------------------------------------------------------------------*/ From e0959e869c17ffd4bb58c99d949210882cbb2fbb Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Thu, 16 Jul 2026 17:17:26 -0700 Subject: [PATCH 184/337] Added `isRecursive` support to lazy-loading stub Updated the `StubLazyLoadingTopicRepository`'s private `FillRequestedPayload()` method to accept `isRecursive`, not only so that it can match the capabilities of `ITopicRepository`, but so it can test the newly available support in e.g., `CachedTopicRepository` for merging unmatched `TopicPayload` into the existing topic graph recursively (012c37c1). This supports the testing of #111, and corresponds to the effort kicked off with the introduction of `ConvergLoadState()` (47769ada). --- .../StubLazyLoadingTopicRepository.cs | 82 +++++++++++++------ 1 file changed, 58 insertions(+), 24 deletions(-) diff --git a/OnTopic.TestDoubles/LazyLoading/StubLazyLoadingTopicRepository.cs b/OnTopic.TestDoubles/LazyLoading/StubLazyLoadingTopicRepository.cs index 02cde23a..b152936f 100644 --- a/OnTopic.TestDoubles/LazyLoading/StubLazyLoadingTopicRepository.cs +++ b/OnTopic.TestDoubles/LazyLoading/StubLazyLoadingTopicRepository.cs @@ -112,6 +112,10 @@ private static Topic BuildEagerScaffold() { var contentTypes = new ContentTypeDescriptor("ContentTypes", "ContentTypeDescriptor", configuration, 3); _ = new ContentTypeDescriptor("Page", "ContentTypeDescriptor", contentTypes, 4); + // Root's own Children property is lazy, matching ITopicRepository's documented Load() defaults; only the Configuration + // subtree required for content type resolution and Save() validation is eagerly scaffolded + ((ITopicLazyLoadable)root).SetLoadState(TopicPayload.Children, LoadState.NotLoaded); + return root; } @@ -189,7 +193,13 @@ private static Topic BuildEagerScaffold() { } // Preload the topic with the requested payload - await FillRequestedPayload(topic, payload, resolveDeferredTargets: false, CancellationToken.None).ConfigureAwait(false); + await FillRequestedPayload( + topic, + payload, + resolveDeferredTargets : false, + isRecursive, + CancellationToken.None + ).ConfigureAwait(false); // Fire the TopicLoaded event, if newly built if (isNewlyBuilt) { @@ -286,7 +296,13 @@ public virtual async Task EnsureLoaded(Topic topic, TopicPayload payload, Cancel } // Call the centralized private helper to fulfill the request - await FillRequestedPayload(topic, payload, resolveDeferredTargets: true, cancellationToken).ConfigureAwait(false); + await FillRequestedPayload( + topic, + payload, + resolveDeferredTargets : true, + isRecursive : false, + cancellationToken + ).ConfigureAwait(false); } @@ -297,9 +313,11 @@ public virtual async Task EnsureLoaded(Topic topic, TopicPayload payload, Cancel /// On a plain Load(), connects resident relationship and reference targets unconditionally, regardless of /// . Either way, loads the data requested in , after filtering out /// any already flags, recording a fetch in the spy for each property filled. Children are - /// fetched from the record store one level at a time; a child already present in (e.g., attached - /// while building an ancestor chain for a deeper call) is - /// reused rather than rebuilt, to avoid colliding with the existing instance already attached to the graph. + /// fetched from the record store one level at a time, unless is set, in which case + /// rides along so every descendant, not merely the immediate children, are + /// filled. A child already present in (e.g., attached while building an ancestor chain for a deeper + /// call) is reused rather than rebuilt, to avoid colliding with + /// the existing instance already attached to the graph. /// /// The topic whose requested payload should be filled. /// The requested flags. @@ -309,11 +327,16 @@ public virtual async Task EnsureLoaded(Topic topic, TopicPayload payload, Cancel /// fill; left by a plain Load(), which only connects targets already present in the graph, /// via . /// + /// + /// Whether a requested boundary should recurse into the entire subtree, + /// rather than filling only the immediate level. + /// /// An optional token used only when resolving deferred targets. private async Task FillRequestedPayload( Topic topic, TopicPayload payload, bool resolveDeferredTargets, + bool isRecursive, CancellationToken cancellationToken ) { @@ -335,7 +358,13 @@ CancellationToken cancellationToken /*-------------------------------------------------------------------------------------------------------------------------- | Filter out any already loaded payloads + >--------------------------------------------------------------------------------------------------------------------------- + | The unfiltered payload is retained for propagation to children below: A property already Loaded on topic (e.g., Root's + | ExtendedAttributes, which defaults to Loaded since Root is never built from a record) doesn't imply descendants are also + | already loaded, so children must still be offered the originally requested payload, not the topic's filtered one \-------------------------------------------------------------------------------------------------------------------------*/ + var requestedPayload = payload; + payload = ((ITopicLazyLoadable)topic).FilterPayload(payload); if (payload is TopicPayload.None) { @@ -345,27 +374,16 @@ CancellationToken cancellationToken // Filters out just the association payloads, if present, for a later gate var associationPayload = payload & (TopicPayload.Relationships | TopicPayload.References); - /*-------------------------------------------------------------------------------------------------------------------------- - | A topic with pending payload must be backed by a record - >--------------------------------------------------------------------------------------------------------------------------- - | A topic that has no corresponding record means it was attached to the graph without ever being built from the store, which - | this stub has no way to fulfill; this represents test setup error, not a legitimate state - \-------------------------------------------------------------------------------------------------------------------------*/ - _store.TryGetValue(topic.Id, out var record); - Contract.Assume( - record, - $"{nameof(StubLazyLoadingTopicRepository)} can only lazily fill topics that are defined in the record store supplied to its " + - $"constructor. Topic {topic.Id} was attached to the graph with a pending {payload} payload, but has no corresponding " + - $"record to fill it from. This is an invalid configuration." - ); - /*-------------------------------------------------------------------------------------------------------------------------- | Children + >--------------------------------------------------------------------------------------------------------------------------- + | Unlike ExtendedAttributes, Children never needs a record of its own to fill: It is resolved purely by scanning the store + | for records whose ParentId matches, including Root, whose top-level records are stored with a null ParentId \-------------------------------------------------------------------------------------------------------------------------*/ if (payload.HasFlag(TopicPayload.Children)) { // Loop through each child record and build the topic from the topic store - foreach (var childRecord in _store.Values.Where(r => r.ParentId == topic.Id).OrderBy(r => r.Id)) { + foreach (var childRecord in _store.Values.Where(r => (r.ParentId?? _root.Id) == topic.Id).OrderBy(r => r.Id)) { // Build the child record, assuming it hasn't already been served if (_served.ContainsKey(childRecord.Id)) { @@ -375,12 +393,16 @@ CancellationToken cancellationToken // Load the rest of the requested payload for the child, mirroring how a Children fetch also pulls in whatever else was // requested (e.g., ExtendedAttributes, VersionHistory) for the whole scope, while relationships and references always - // ride along for free; the child's own Children are left deferred - var childPayload = (payload & ~TopicPayload.Children) | TopicPayload.Relationships | TopicPayload.References; - await FillRequestedPayload(child, childPayload, resolveDeferredTargets: false, cancellationToken).ConfigureAwait(false); + // ride along for free. When isRecursive, Children rides along too, so the fill descends into the entire subtree rather + // than stopping at one level. This uses requestedPayload, not the filtered payload, since a property that is already + // Loaded on a topic doesn't imply it's also already loaded on the child + var childPayload = (isRecursive? requestedPayload : requestedPayload & ~TopicPayload.Children) + | TopicPayload.Relationships + | TopicPayload.References; + await FillRequestedPayload(child, childPayload, resolveDeferredTargets: false, isRecursive, cancellationToken).ConfigureAwait(false); // Fire the TopicLoaded event - OnTopicLoaded(new(child, isRecursive: false)); + OnTopicLoaded(new(child, isRecursive)); } @@ -392,9 +414,21 @@ CancellationToken cancellationToken /*-------------------------------------------------------------------------------------------------------------------------- | Extended attributes + >--------------------------------------------------------------------------------------------------------------------------- + | Unlike Children, this requires a backing record; a topic with a pending ExtendedAttributes payload but no corresponding + | record means it was attached to the graph without ever being built from the store, which this stub has no way to fulfill, + | representing test setup error, not a legitimate state \-------------------------------------------------------------------------------------------------------------------------*/ if (payload.HasFlag(TopicPayload.ExtendedAttributes)) { + _store.TryGetValue(topic.Id, out var record); + Contract.Assume( + record, + $"{nameof(StubLazyLoadingTopicRepository)} can only lazily fill topics that are defined in the record store supplied to " + + $"its constructor. Topic {topic.Id} was attached to the graph with a pending {payload} payload, but has no corresponding " + + $"record to fill it from. This is an invalid configuration." + ); + // Load each of the extended attributes from the data store foreach (var attribute in record.ExtendedAttributes) { rawTopic.Attributes.SetValue(attribute.Key, attribute.Value, markDirty: false, isExtendedAttribute: true); From b5da9449a9bf84d265341d79dedfb05dcf4e21c0 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Thu, 16 Jul 2026 18:07:27 -0700 Subject: [PATCH 185/337] Fix `LoadTopicGraph()` issue with `Refresh()` The updates I've been making to `LoadTopicGraph()` and `EnsureLoaded()` around setting `Children.LoadState` (c998de19) via the new `ConvergeLoadState()` (47769ada) work for the primary `Load()` path with the `GetTopics` stored procedure, but fail with the alternate `Refresh()` path with the `GetTopicUpdates` stored procedure. This fixes that issue. --- OnTopic.Data.Sql/SqlDataReaderExtensions.cs | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs index bb8ecd69..da36b17d 100644 --- a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs +++ b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs @@ -117,12 +117,14 @@ internal static class SqlDataReaderExtensions { preExistingIds.Contains(addedTopic.Id), isComplete: !hasChildren ); - } - // Any rows after the seed are a genuine child, indicating that the parent's full child set was returned. The parent may - // be unresolved (e.g., GetTopicUpdates' unordered, possibly-disconnected Refresh() batch), hence the null-conditional. - if (seedTopic is not null && addedTopic != seedTopic) { - (addedTopic.Parent as ITopicLazyLoadable)?.SetLoadState(TopicPayload.Children, LoadState.Loaded); + // Any rows after the seed are a genuine child, indicating that the parent's full child set was returned. This is only + // meaningful here, where HasChildren is populated (GetTopics' ordered, complete result set); GetTopicUpdates' + // Refresh() batch leaves HasChildren NULL for every row, since it is an unordered, possibly disconnected set of changed + // topics, not a complete child listing. The parent may also be unresolved, hence the null-conditional. + if (seedTopic is not null && addedTopic != seedTopic) { + (addedTopic.Parent as ITopicLazyLoadable)?.SetLoadState(TopicPayload.Children, LoadState.Loaded); + } } } From 3ff79e3eb066072eb22747b1548c26b7a54b61f6 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Thu, 16 Jul 2026 18:19:19 -0700 Subject: [PATCH 186/337] Introduce unit test to confirm `Refresh()` fix This patches a gap in unit tests which confirms the recent fix for the `SqlTopicRepository.Refresh()` path (b5da9449), contributing to the unit testing for #111. --- OnTopic.Tests/SqlTopicRepositoryTest.cs | 36 +++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/OnTopic.Tests/SqlTopicRepositoryTest.cs b/OnTopic.Tests/SqlTopicRepositoryTest.cs index 28c37fca..af409844 100644 --- a/OnTopic.Tests/SqlTopicRepositoryTest.cs +++ b/OnTopic.Tests/SqlTopicRepositoryTest.cs @@ -626,6 +626,42 @@ public async Task LoadTopicGraph_DisconnectedBatch_DoesNotThrow() { } + /*============================================================================================================================ + | TEST: LOAD TOPIC GRAPH: DISCONNECTED BATCH: PRESERVES NOT LOADED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Calls with a GetTopicUpdates-shaped batch naming a existing, + /// parent's child, and confirms the parent's is + /// preserved, rather than being misread as a complete child listing. + /// + /// + /// A Refresh() batch is an arbitrary, unordered set of individually modified topics, not a complete child listing + /// the way a GetTopics result is. Without gating on HasChildren (always NULL in this shape), any row + /// naming a resident parent, other than the batch's arbitrary first row, would be misread as proof the parent's full child + /// set was returned, silently preventing it from lazy loading. + /// + [Fact] + public async Task LoadTopicGraph_DisconnectedBatch_PreservesNotLoaded() { + + var root = new Topic("Root", "Container", null, 1); + var parent = new Topic("Parent", "Container", root, 2); + var rawParent = (ITopicBackingAccessor)parent; + + rawParent.Children.LoadState = LoadState.NotLoaded; + + using var topics = new TopicsDataTable(); + + topics.AddRow(99, "Orphan", "Page", 999); + topics.AddRow(3, "Child", "Page", 2); + + using var tableReader = new DataTableReader(topics); + + await tableReader.LoadTopicGraph(referenceTopic: parent, cancellationToken: CancellationToken); + + Assert.Equal(LoadState.NotLoaded, rawParent.Children.LoadState); + + } + /*============================================================================================================================ | TEST: LOAD TOPIC GRAPH: WHOLE TREE LOAD: CONVERGES NON-LEAF REGION NODES \---------------------------------------------------------------------------------------------------------------------------*/ From d347e3c9f813471d7a28ff5208a9f243ec2d1681 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Thu, 16 Jul 2026 18:22:54 -0700 Subject: [PATCH 187/337] Introduce unit test for `HasChildren` loadstate This ensures that the tests for the use of `ConvergeLoadState()` (c998de19) on child topics (c998de19, 9a7594a6) cover the scenario where `HasChildren` is returned, and no children are returned, thus addressing the gap in the original unit tests (86aaf98d), and patching the testing for the lazy-loading implementation (#111). --- OnTopic.Tests/SqlTopicRepositoryTest.cs | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/OnTopic.Tests/SqlTopicRepositoryTest.cs b/OnTopic.Tests/SqlTopicRepositoryTest.cs index af409844..a6b2b4a4 100644 --- a/OnTopic.Tests/SqlTopicRepositoryTest.cs +++ b/OnTopic.Tests/SqlTopicRepositoryTest.cs @@ -918,6 +918,29 @@ public async Task LoadTopicGraph_WithHasChildrenAndLoadedChildren_ReturnsChildre } + /*============================================================================================================================ + | TEST: LOAD TOPIC GRAPH: WITH HAS CHILDREN AND NO RETURNED CHILDREN: SETS NOT LOADED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Calls with a shallow, single-row result set where HasChildren + /// is but no child rows are returned, confirming is (i.e., the seed itself is known to have children, but none were loaded). + /// + [Fact] + public async Task LoadTopicGraph_WithHasChildrenAndNoReturnedChildren_SetsNotLoaded() { + + using var topics = new TopicsDataTable(); + + topics.AddRow(1, "Root", "Container", hasChildren: true); + + using var tableReader = new DataTableReader(topics); + + var topic = await tableReader.LoadTopicGraph(1, cancellationToken: CancellationToken); + + Assert.False(((ITopicLazyLoadable)topic)?.IsLoaded(TopicPayload.Children)); + + } + /*============================================================================================================================ | TEST: LOAD TOPIC GRAPH: WITH HAS CHILDREN ON ANCESTOR AND LOADED SUBTREE: SETS LOAD STATE CORRECTLY \---------------------------------------------------------------------------------------------------------------------------*/ From 1eb817de742a0e605f7cee589b1cc68bf1ae89db Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Thu, 16 Jul 2026 18:40:18 -0700 Subject: [PATCH 188/337] Introduce new `GetSitemap` sproc The new `GetSitemap` stored procedure will support a forthcoming `ISitemapTopicRepository` and corresponding `SitemapTopicRepository` for handling the `SitemapController`. This is useful because, with the lazy-loading project (#111), we're expecting ASP.NET Core applications to only load sparsely populated, partial topic graphs, whereas the `SitemapController` needs the entire graph. If it needed to load and cache the entire tree, that would defeat the benefit of lazy loading. This stored procedure provides the bare-minimum data required by the `SitemapController`, which is much faster than loading even the entire topic graph with indexed attributes, and can then be aggressively cached to prevent it from being requested again. --- .../OnTopic.Data.Sql.Database.sqlproj | 1 + .../Stored Procedures/GetSitemap.sql | 47 +++++++++++++++++++ 2 files changed, 48 insertions(+) create mode 100644 OnTopic.Data.Sql.Database/Stored Procedures/GetSitemap.sql diff --git a/OnTopic.Data.Sql.Database/OnTopic.Data.Sql.Database.sqlproj b/OnTopic.Data.Sql.Database/OnTopic.Data.Sql.Database.sqlproj index 631bb12e..e631140e 100644 --- a/OnTopic.Data.Sql.Database/OnTopic.Data.Sql.Database.sqlproj +++ b/OnTopic.Data.Sql.Database/OnTopic.Data.Sql.Database.sqlproj @@ -93,6 +93,7 @@ + diff --git a/OnTopic.Data.Sql.Database/Stored Procedures/GetSitemap.sql b/OnTopic.Data.Sql.Database/Stored Procedures/GetSitemap.sql new file mode 100644 index 00000000..b18c0c0d --- /dev/null +++ b/OnTopic.Data.Sql.Database/Stored Procedures/GetSitemap.sql @@ -0,0 +1,47 @@ +-------------------------------------------------------------------------------------------------------------------------------- +-- GET SITEMAP +-------------------------------------------------------------------------------------------------------------------------------- +-- Returns the minimal data the sitemap renders: The topic rows, then the handful of indexed attributes the sitemap evaluates. +-- SqlDataReaderExtensions.LoadTopicGraph stitches these two sets and passed over the result sets it would otherwise read +-- (extended attributes, relationships, references, history), which this sproc simply does not return. Deliberately omits the +-- nested-set descent, extended-attribute blobs, relationships, references, and version history. +-- +-- HasChildren and HasExtendedAttributes must be present so LoadTopicGraph's reader contract is satisfied (it reads both columns +-- unconditionally), but their values don't need to be computed: This sproc returns the entire flattened tree in one pass, so +-- every topic's children are already present in the graph regardless of the flag, and the graph is not subject to lazy-loading +-- (i.e., no ITopicLazyLoader stamped), so LoadState is never consulted to trigger a fill regardless. NULL leaves both +-- boundaries at their default of LoadState.Loaded (KeyedTopicCollection's default), matching the resolver-free invariant. +-------------------------------------------------------------------------------------------------------------------------------- + +CREATE PROCEDURE [dbo].[GetSitemap] +AS + +-------------------------------------------------------------------------------------------------------------------------------- +-- SELECT TOPICS +-------------------------------------------------------------------------------------------------------------------------------- +SELECT Topics.TopicID, + Topics.ContentType, + Topics.ParentID, + Topics.TopicKey, + HasChildren = CAST(NULL AS BIT), + HasExtendedAttributes = CAST(NULL AS BIT) +FROM Topics AS Topics +ORDER BY Topics.RangeLeft + +-------------------------------------------------------------------------------------------------------------------------------- +-- SELECT ATTRIBUTES +-------------------------------------------------------------------------------------------------------------------------------- +-- Filtered to exactly the keys AddTopic evaluates plus LastModified; this IN list is coupled to the controller's inclusion +-- logic and must grow with it. +SELECT Attributes.TopicID, + Attributes.AttributeKey, + Attributes.AttributeValue, + Attributes.Version +FROM AttributeIndex AS Attributes +WHERE Attributes.AttributeKey IN ( + 'IsPrivateBranch', + 'NoIndex', + 'IsDisabled', + 'Url', + 'LastModified' + ) \ No newline at end of file From f9aa14d23fed4999dbe92730192bc6a6894dd4c0 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Thu, 16 Jul 2026 18:50:22 -0700 Subject: [PATCH 189/337] Established an `ISitemapTopicRepository` interface MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This provides a lightweight variation of the `ITopicRepository` that will be used for loading e.g., the new `GetSitemap` stored procedure (at least for the `OnTopic.Data.Sql` implementation; 1eb817de). Unlike `ITopicRepository`, it only has one method—`Load()`—and no `Save()`, `Delete()`, `Move()`, or `Refresh()` methods. This contributes to the lazy-loading project (#111). --- .../Repositories/ISitemapTopicRepository.cs | 26 +++++++++++++++++++ 1 file changed, 26 insertions(+) create mode 100644 OnTopic/Repositories/ISitemapTopicRepository.cs diff --git a/OnTopic/Repositories/ISitemapTopicRepository.cs b/OnTopic/Repositories/ISitemapTopicRepository.cs new file mode 100644 index 00000000..23650b8b --- /dev/null +++ b/OnTopic/Repositories/ISitemapTopicRepository.cs @@ -0,0 +1,26 @@ +/*============================================================================================================================== +| Author Ignia, LLC +| Client Ignia, LLC +| Project Topics Library +\=============================================================================================================================*/ +namespace OnTopic.Repositories; + +/*============================================================================================================================== +| INTERFACE: SITEMAP TOPIC REPOSITORY +\-----------------------------------------------------------------------------------------------------------------------------*/ +/// +/// Provides a narrow, read-only seam for retrieving the minimal graph required to render the sitemap, +/// without exposing the full read/write surface of . +/// +public interface ISitemapTopicRepository { + + /*============================================================================================================================ + | METHOD: LOAD + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Loads a detached, lightweight graph containing only the fields the sitemap renders. The graph is + /// independent of any shared cache and is expected to be discarded once the response is rendered. + /// + Task Load(); + +} //Interface \ No newline at end of file From bfd6fe2bc28ae0085ed2b3939175b326810b7ce2 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Thu, 16 Jul 2026 19:03:45 -0700 Subject: [PATCH 190/337] Introduced the `SqlSitemapTopicRepository` This provides a concrete implementation of the new `ISitemapTopicRepository` interface (f9aa14d2) for Microsoft SQL Server, and a client of the new `GetSitemap` stored procedure (1eb817de), thus satisfying the core functionality of the `SitemapController` update to mitigate limitations of the new lazy-loading project (#111). --- OnTopic.Data.Sql/SqlSitemapTopicRepository.cs | 102 ++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 OnTopic.Data.Sql/SqlSitemapTopicRepository.cs diff --git a/OnTopic.Data.Sql/SqlSitemapTopicRepository.cs b/OnTopic.Data.Sql/SqlSitemapTopicRepository.cs new file mode 100644 index 00000000..b4bce0a6 --- /dev/null +++ b/OnTopic.Data.Sql/SqlSitemapTopicRepository.cs @@ -0,0 +1,102 @@ +/*============================================================================================================================== +| Author Ignia, LLC +| Client Ignia, LLC +| Project Topics Library +\=============================================================================================================================*/ +using OnTopic.Repositories; + +namespace OnTopic.Data.Sql; + +/*============================================================================================================================== +| CLASS: SQL SITEMAP TOPIC REPOSITORY +\-----------------------------------------------------------------------------------------------------------------------------*/ +/// +/// Provides data access to the minimal graph required to render the sitemap, sourced from Microsoft SQL +/// Server. +/// +/// +/// Concrete implementation of the interface. Unlike , +/// accepts no referenceTopic to merge into, raises no +/// event, and stamps no : Each call returns an entirely fresh, detached graph, with no +/// relationship to any other topic graph in memory, intended to be discarded once the response is rendered. Caching can be +/// done at the controller level of the rendered XML. +/// +public class SqlSitemapTopicRepository : ISitemapTopicRepository { + + /*============================================================================================================================ + | PRIVATE VARIABLES + \---------------------------------------------------------------------------------------------------------------------------*/ + private readonly string _connectionString; + + /*============================================================================================================================ + | CONSTRUCTOR + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Instantiates a new instance of the with a dependency on a connection string to + /// provide necessary access to a SQL database. + /// + /// A connection string to a SQL server that contains the Topics database. + /// A new instance of the . + public SqlSitemapTopicRepository(string connectionString) { + + /*-------------------------------------------------------------------------------------------------------------------------- + | Validate parameters + \-------------------------------------------------------------------------------------------------------------------------*/ + Contract.Requires(!String.IsNullOrWhiteSpace(connectionString), nameof(connectionString)); + + /*-------------------------------------------------------------------------------------------------------------------------- + | Set private fields + \-------------------------------------------------------------------------------------------------------------------------*/ + _connectionString = connectionString; + + } + + /*============================================================================================================================ + | METHOD: LOAD + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + public async Task Load() { + + /*-------------------------------------------------------------------------------------------------------------------------- + | Establish database connection + \-------------------------------------------------------------------------------------------------------------------------*/ + var topic = (Topic?)null; + + using var connection = new SqlConnection(_connectionString); + using var command = new SqlCommand("GetSitemap", connection) { + CommandType = CommandType.StoredProcedure, + CommandTimeout = 120 + }; + + /*-------------------------------------------------------------------------------------------------------------------------- + | Process database query + \-------------------------------------------------------------------------------------------------------------------------*/ + try { + await connection.OpenAsync().ConfigureAwait(false); + using var reader = (SqlDataReader)await command.ExecuteReaderAsync().ConfigureAwait(false); + topic = await reader.LoadTopicGraph(referenceTopic: null, markDirty: false).ConfigureAwait(false); + } + + /*-------------------------------------------------------------------------------------------------------------------------- + | Catch exception + \-------------------------------------------------------------------------------------------------------------------------*/ + catch (SqlException exception) { + throw new TopicRepositoryException($"Topics failed to load: '{exception.Message}'", exception); + } + + /*-------------------------------------------------------------------------------------------------------------------------- + | Validate results + \-------------------------------------------------------------------------------------------------------------------------*/ + Contract.Assume( + topic, + "The 'GetSitemap' stored procedure did not return a topic graph." + ); + + /*-------------------------------------------------------------------------------------------------------------------------- + | Return objects + \-------------------------------------------------------------------------------------------------------------------------*/ + return topic; + + } + +} //Class \ No newline at end of file From c199203453defdcdd2ea4727573048eed7801b1d Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Thu, 16 Jul 2026 19:26:11 -0700 Subject: [PATCH 191/337] Removed the legacy extended sitemap The "extended" sitemap was intended to provide custom metadata to sitemap consumers so they could be searched by. This used to be supported by the Google Custom Search Engine for custom site searches. Google retired that implementation, and its replacement, Google Programmable Search Engine, doesn't support that, nor do other common search engine products. Since this doesn't have a clear current use case, and it necessitates the expensive eager-loading of a full topic graph, which is in contrast to the lazy-loading update (#111), I'm making the call to retire this functionality. There is an argument for providing a sitemap with e.g., schema.org or other metadata support. That is a separate feature, however, which requires mapping attributes on a per content type basis to semantic web structured metadata supported by the sitemap format and popular indexers, like Google. This allows us to remove the `Extended` action, and the `includeMetadata` arguments to the `Index` action, `GenerateSitemap ()` and `AddTopic()`, all of the local functions that supported `includeMetadata` in `AddTopic()`, plus the `ExcludedAttributes` collection. It also allows us to get rid of the `_pagemapNamespace` which referenced Google's extensions of the Sitemap.org schema. This removes a lot of complexity, dramatically simplifying the `SitemapController`. --- .../Controllers/SitemapController.cs | 113 ++---------------- 1 file changed, 8 insertions(+), 105 deletions(-) diff --git a/OnTopic.AspNetCore.Mvc/Controllers/SitemapController.cs b/OnTopic.AspNetCore.Mvc/Controllers/SitemapController.cs index e3841138..ea2a93ff 100644 --- a/OnTopic.AspNetCore.Mvc/Controllers/SitemapController.cs +++ b/OnTopic.AspNetCore.Mvc/Controllers/SitemapController.cs @@ -26,12 +26,6 @@ namespace OnTopic.AspNetCore.Mvc.Controllers; /// types are excluded or skipped can be configured, respectively, by modifying the static and collections. /// -/// -/// The action enables an extended sitemap with Google's custom PageMap schema for -/// exposing , , and . By -/// default, some content attributes, such as Body, IsDisabled, and NoIndex, are hidden. This list -/// can be modified by updating the static collection. -/// /// /// /// The used to retrieve instances for the sitemap. @@ -47,7 +41,6 @@ public class SitemapController(ITopicRepository topicRepository) : Controller { | CONSTANTS \---------------------------------------------------------------------------------------------------------------------------*/ private static readonly XNamespace _sitemapNamespace = "http://www.sitemaps.org/schemas/sitemap/0.9"; - private static readonly XNamespace _pagemapNamespace = "http://www.google.com/schemas/sitemap-pagemap/1.0"; /*============================================================================================================================ | EXCLUDED CONTENT TYPES @@ -70,23 +63,6 @@ public class SitemapController(ITopicRepository topicRepository) : Controller { "Container" }; - /*============================================================================================================================ - | EXCLUDED ATTRIBUTES - \---------------------------------------------------------------------------------------------------------------------------*/ - /// - /// Specifies what attributes should not be listed in the sitemap. - /// - public static Collection ExcludedAttributes { get; } = new() { - "Body", - "IsDisabled", - "ParentID", //Legacy, but exposed for avoid leacking legacy data - "TopicID", //Legacy, but exposed for avoid leacking legacy data - "ContentType", //Legacy, but exposed for avoid leacking legacy data - "IsHidden", - "NoIndex", - "SortOrder" - }; - /*============================================================================================================================ | GET: /SITEMAP \---------------------------------------------------------------------------------------------------------------------------*/ @@ -94,9 +70,8 @@ public class SitemapController(ITopicRepository topicRepository) : Controller { /// Provides the Sitemap.org sitemap for the site. /// /// Optionally enables indentation of XML elements in output for human readability. - /// Optionally enables extended metadata associated with each topic. /// A Sitemap.org sitemap. - public ActionResult Index(bool indent = false, bool includeMetadata = false) { + public ActionResult Index(bool indent = false) { /*-------------------------------------------------------------------------------------------------------------------------- | Ensure topics are loaded @@ -113,7 +88,7 @@ public ActionResult Index(bool indent = false, bool includeMetadata = false) { | Establish sitemap \-------------------------------------------------------------------------------------------------------------------------*/ var declaration = new XDeclaration("1.0", "utf-8", "no"); - var sitemap = GenerateSitemap(rootTopic, includeMetadata); + var sitemap = GenerateSitemap(rootTopic); var settings = indent? SaveOptions.None : SaveOptions.DisableFormatting; /*-------------------------------------------------------------------------------------------------------------------------- @@ -123,21 +98,6 @@ public ActionResult Index(bool indent = false, bool includeMetadata = false) { } - /*============================================================================================================================ - | GET: /SITEMAP/EXTENDED - \---------------------------------------------------------------------------------------------------------------------------*/ - /// - /// Provides the Sitemap.org sitemap for the site, including extended metadata attributes. - /// - /// - /// Introducing the metadata makes the sitemap considerably larger. However, it also means that some agents will index the - /// additional information and make it available for querying. For instance, the (now defunct) Google Custom Search Engine - /// (CSE) would previously allow queries to be filtered based on metadata attributes exposed via the sitemap. - /// - /// Optionally enables indentation of XML elements in output for human readability. - /// A Sitemap.org sitemap. - public ActionResult Extended(bool indent = false) => Index(indent, true); - /*============================================================================================================================ | METHOD: GENERATE SITEMAP \---------------------------------------------------------------------------------------------------------------------------*/ @@ -145,13 +105,12 @@ public ActionResult Index(bool indent = false, bool includeMetadata = false) { /// Given a root topic, generates an XML-formatted sitemap. /// /// The topic to add to the sitemap. - /// Optionally enables extended metadata associated with each topic. /// A Sitemap.org sitemap. - private XDocument GenerateSitemap(Topic rootTopic, bool includeMetadata = false) => + private XDocument GenerateSitemap(Topic rootTopic) => new( new XElement(_sitemapNamespace + "urlset", from topic in rootTopic.Children - select AddTopic(topic, includeMetadata) + select AddTopic(topic) ) ); @@ -159,11 +118,10 @@ select AddTopic(topic, includeMetadata) | METHOD: ADD TOPIC \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Given a , adds it to a given . + /// Given a , returns the sitemap url elements for it and its descendants. /// /// The topic to add to the sitemap. - /// Optionally enables extended metadata associated with each topic. - private List AddTopic(Topic topic, bool includeMetadata = false) { + private List AddTopic(Topic topic) { /*-------------------------------------------------------------------------------------------------------------------------- | Establish return collection @@ -193,12 +151,7 @@ private List AddTopic(Topic topic, bool includeMetadata = false) { new XElement(_sitemapNamespace + "loc", domain + topic.GetWebPath()), new XElement(_sitemapNamespace + "changefreq", "monthly"), new XElement(_sitemapNamespace + "lastmod", lastModified.ToString("yyyy-MM-dd", CultureInfo.InvariantCulture)), - new XElement(_sitemapNamespace + "priority", 1), - includeMetadata? new XElement(_pagemapNamespace + "PageMap", - getAttributes(), - getRelationships(), - getReferences() - ) : null + new XElement(_sitemapNamespace + "priority", 1) ); if ( !SkippedContentTypes.Any(c => topic.ContentType?.Equals(c, StringComparison.OrdinalIgnoreCase)?? false) && @@ -213,61 +166,11 @@ private List AddTopic(Topic topic, bool includeMetadata = false) { | Iterate over children \-------------------------------------------------------------------------------------------------------------------------*/ foreach (var childTopic in topic.Children) { - topics.AddRange(AddTopic(childTopic, includeMetadata)); + topics.AddRange(AddTopic(childTopic)); } return topics; - /*-------------------------------------------------------------------------------------------------------------------------- - | Get attributes - \-------------------------------------------------------------------------------------------------------------------------*/ - XElement getAttributes() => - new(_pagemapNamespace + "DataObject", - new XAttribute("type", "Attributes"), - new XElement(_pagemapNamespace + "Attribute", - new XAttribute("name", "ContentType"), - new XText(topic.ContentType?? "Page") - ), - from attribute in topic.Attributes - let attributeValue = topic.Attributes.GetValue(attribute.Key) - where !ExcludedAttributes.Contains(attribute.Key, StringComparer.OrdinalIgnoreCase) - where attributeValue?.Length < 256 - select new XElement(_pagemapNamespace + "Attribute", - new XAttribute("name", attribute.Key), - new XText(attributeValue ?? "") - ) - ); - - /*-------------------------------------------------------------------------------------------------------------------------- - | Get relationships - \-------------------------------------------------------------------------------------------------------------------------*/ - IEnumerable getRelationships() => - from relationship in topic.Relationships - select new XElement(_pagemapNamespace + "DataObject", - new XAttribute("type", relationship.Key), - from relatedTopic in relationship.Values - select new XElement(_pagemapNamespace + "Attribute", - new XAttribute("name", "TopicKey"), - new XText(relatedTopic.GetUniqueKey().Replace("Root:", "", StringComparison.OrdinalIgnoreCase)) - ) - ); - - /*-------------------------------------------------------------------------------------------------------------------------- - | Get references - \-------------------------------------------------------------------------------------------------------------------------*/ - XElement? getReferences() => - topic.References.Count is 0? - null : - new XElement(_pagemapNamespace + "DataObject", - new XAttribute("type", "References"), - from reference in topic.References - where reference.Value is not null - select new XElement(_pagemapNamespace + "Attribute", - new XAttribute("name", reference.Key), - new XText(reference.Value!.GetUniqueKey().Replace("Root:", "", StringComparison.OrdinalIgnoreCase)) - ) - ); - } } //Class \ No newline at end of file From c0a919eed8f9af5c28e96052f05474930ad62c05 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Thu, 16 Jul 2026 19:50:56 -0700 Subject: [PATCH 192/337] Integrate `ISitemapTopicRepository ` in controller Integrated the new `ISitemapTopicRepository` (f9aa14d2) into the existing `SitemapController`, replacing the reliance on the full read/write `ITopicRepository`, thus mitigating the limitations of the new lazy-loading project (#111) with regards to the sitemap. As part of this, I also made the `SitemapController`'s `Index()` asynchronous, and were able to get rid of the prior guard for `rootTopic` since the new `ISitemapTopicRepository` (f9aa14d2) and e.g., its `SqlSitemapTopicRepository` implementation (bfd6fe2b), already guard that and, thus, are able to guarantee that the return from `Load()` is not null, unlike the previous `ITopicRepository` contract. I also implemented some collection expressions that had previously been missed (688c69b7) while I was at it. --- .../Controllers/SitemapController.cs | 33 +++++++------------ 1 file changed, 11 insertions(+), 22 deletions(-) diff --git a/OnTopic.AspNetCore.Mvc/Controllers/SitemapController.cs b/OnTopic.AspNetCore.Mvc/Controllers/SitemapController.cs index ea2a93ff..8249c912 100644 --- a/OnTopic.AspNetCore.Mvc/Controllers/SitemapController.cs +++ b/OnTopic.AspNetCore.Mvc/Controllers/SitemapController.cs @@ -5,7 +5,6 @@ \=============================================================================================================================*/ using System.Collections.ObjectModel; using System.Globalization; -using System.Xml; using System.Xml.Linq; using OnTopic.Attributes; @@ -19,23 +18,21 @@ namespace OnTopic.AspNetCore.Mvc.Controllers; /// child topics to generate the appropriate markup. /// /// -/// -/// By default, some s are excluded based on their content types—which includes not only the -/// , but also all of its descendents. Other s are skipped, also based on -/// their content types; in this case, the is excluded, but its descendents are not. What content -/// types are excluded or skipped can be configured, respectively, by modifying the static and collections. -/// +/// By default, some s are excluded based on their content types—which includes not only the +/// , but also all of its descendents. Other s are skipped, also based on +/// their content types; in this case, the is excluded, but its descendents are not. What content +/// types are excluded or skipped can be configured, respectively, by modifying the static and collections. /// /// -/// The used to retrieve instances for the sitemap. +/// The used to retrieve the minimal graph for the sitemap. /// -public class SitemapController(ITopicRepository topicRepository) : Controller { +public class SitemapController(ISitemapTopicRepository topicRepository) : Controller { /*============================================================================================================================ | PRIVATE VARIABLES \---------------------------------------------------------------------------------------------------------------------------*/ - private readonly ITopicRepository _topicRepository = Contract.Requires(topicRepository); + private readonly ISitemapTopicRepository _topicRepository = Contract.Requires(topicRepository); /*============================================================================================================================ | CONSTANTS @@ -48,9 +45,7 @@ public class SitemapController(ITopicRepository topicRepository) : Controller { /// /// Specifies what content types should not be listed in the sitemap, including any descendents. /// - public static Collection ExcludedContentTypes { get; } = new() { - "List" - }; + public static Collection ExcludedContentTypes { get; } = ["List"]; /*============================================================================================================================ | SKIPPED CONTENT TYPES @@ -58,10 +53,10 @@ public class SitemapController(ITopicRepository topicRepository) : Controller { /// /// Specifies what content types should not be listed in the sitemap—but whose descendents should still be evaluated. /// - public static Collection SkippedContentTypes { get; } = new() { + public static Collection SkippedContentTypes { get; } = [ "PageGroup", "Container" - }; + ]; /*============================================================================================================================ | GET: /SITEMAP @@ -78,12 +73,6 @@ public ActionResult Index(bool indent = false) { \-------------------------------------------------------------------------------------------------------------------------*/ var rootTopic = _topicRepository.Load().GetAwaiter().GetResult(); - Contract.Assume( - rootTopic, - $"The topic graph could not be successfully loaded from the {nameof(ITopicRepository)} instance. The " + - $"{nameof(SitemapController)} is unable to establish a local copy to work off of." - ); - /*-------------------------------------------------------------------------------------------------------------------------- | Establish sitemap \-------------------------------------------------------------------------------------------------------------------------*/ From 755c060b7a2c5fa2e8941ee968c4fde4bbf98793 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Thu, 16 Jul 2026 20:16:28 -0700 Subject: [PATCH 193/337] Introduced `StubSitemapTopicRepository` This provides a stub for testing the new `ISitemapTopicRepository` (f9aa14d2) and its integration into the `SitemapController` (c0a919ee). While the actual `SqlSitemapTopicRepository` (bfd6fe2b) relies on a distinct data source via the `GetSitemap` stored procedure (1eb817de), for test purposes, this just provides a wrapper on top of an existing `ITopicRepository`, which in practice is expected to be the `StubTopicRepository`, which provides an eager-loaded test version of the `ITopicRepository`, thus preventing us from reinventing the wheel on loading the data. While, yes, this is providing more data than a real `ISitemapTopicRepository`'s topics would provide, none of our tests are affected by that, and the real issue of testing e.g., `SqlSitemapTopicRepository` and the `GetSitemap` stored procedure would require a test SQL database regardless, so is a different task. This contributes to testing of the `ISitemapTopicRepository` (f9aa14d2) and `SitemapController` (c0a919ee), and is loosely associated with the lazy-loading testing (#111) in that this addresses a gap left by lazy-loading with the sitemap. --- .../StubSitemapTopicRepository.cs | 42 +++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 OnTopic.TestDoubles/StubSitemapTopicRepository.cs diff --git a/OnTopic.TestDoubles/StubSitemapTopicRepository.cs b/OnTopic.TestDoubles/StubSitemapTopicRepository.cs new file mode 100644 index 00000000..585f63ce --- /dev/null +++ b/OnTopic.TestDoubles/StubSitemapTopicRepository.cs @@ -0,0 +1,42 @@ +/*============================================================================================================================== +| Author Ignia, LLC +| Client Ignia, LLC +| Project Topics Library +\=============================================================================================================================*/ +using OnTopic.Internal.Diagnostics; +using OnTopic.Repositories; + +namespace OnTopic.TestDoubles; + +/*============================================================================================================================== +| CLASS: STUB SITEMAP TOPIC REPOSITORY +\-----------------------------------------------------------------------------------------------------------------------------*/ +/// +/// Provides an backed by an existing , for testing +/// consumers of without a SQL-backed SqlSitemapTopicRepository. +/// +/// +/// Unlike a SQL-backed implementation, this does not source a lean, purpose-built graph; it simply defers to the wrapped +/// 's own , requesting +/// the full descendant tree explicitly since isRecursive defaults to false. +/// +/// The to source the sitemap's topic graph from. +[ExcludeFromCodeCoverage] +public class StubSitemapTopicRepository(ITopicRepository topicRepository) : ISitemapTopicRepository { + + /*============================================================================================================================ + | PRIVATE VARIABLES + \---------------------------------------------------------------------------------------------------------------------------*/ + private readonly ITopicRepository _topicRepository = Contract.Requires(topicRepository); + + /*============================================================================================================================ + | METHOD: LOAD + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + public async Task Load() { + var topic = await _topicRepository.Load(-1, isRecursive: true).ConfigureAwait(false); + Contract.Assume(topic, "The wrapped ITopicRepository did not return a topic graph."); + return topic; + } + +} //Class \ No newline at end of file From 3b81cf1ed2f96dcf9b57048a4d868b9e60dd2786 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Thu, 16 Jul 2026 20:22:08 -0700 Subject: [PATCH 194/337] Wire-up `SqlSitemapTopicRepository` in `Host` This ensures that the `SitemapController` is correctly receiving a now-expected (c0a919ee) `ISitemapTopicRepository` (f9aa14d2), and specifically the production-ready `SqlSitemapTopicRepository` (bfd6fe2b). This addresses a gap in `SitemapController` introduced by the new lazy-loading project (#111). --- OnTopic.AspNetCore.Mvc.Host/SampleActivator.cs | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/OnTopic.AspNetCore.Mvc.Host/SampleActivator.cs b/OnTopic.AspNetCore.Mvc.Host/SampleActivator.cs index 9a4263ae..c424377d 100644 --- a/OnTopic.AspNetCore.Mvc.Host/SampleActivator.cs +++ b/OnTopic.AspNetCore.Mvc.Host/SampleActivator.cs @@ -36,6 +36,7 @@ public class SampleActivator : IControllerActivator, IViewComponentActivator { private readonly ITypeLookupService _typeLookupService; private readonly ITopicMappingService _topicMappingService; private readonly ITopicRepository _topicRepository; + private readonly ISitemapTopicRepository _sitemapTopicRepository; private DateTime _cacheLastUpdated = DateTime.UtcNow; /*============================================================================================================================ @@ -72,6 +73,7 @@ public SampleActivator(string connectionString) { | Preload repository \-------------------------------------------------------------------------------------------------------------------------*/ _topicRepository = cachedTopicRepository; + _sitemapTopicRepository = new SqlSitemapTopicRepository(connectionString); _typeLookupService = new DynamicTopicViewModelLookupService(); _topicMappingService = new TopicMappingService(_topicRepository, _typeLookupService); @@ -124,7 +126,7 @@ public object Create(ControllerContext context) { nameof(ErrorController) => new ErrorController(_topicRepository, _topicMappingService), nameof(SitemapController) => - new SitemapController(_topicRepository), + new SitemapController(_sitemapTopicRepository), nameof(RedirectController) => new RedirectController(_topicRepository), _ => throw new InvalidOperationException($"Unknown controller {type.Name}") From 79ec7a69dd427bb6bc861fd44fe1bd985eedd5d3 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Thu, 16 Jul 2026 20:23:51 -0700 Subject: [PATCH 195/337] Wire-up `StubSitemapTopicRepository` in `Host` This ensures that the `SitemapController` is correctly receiving a now-expected (c0a919ee) `ISitemapTopicRepository` (f9aa14d2), and specifically the test double `StubSitemapTopicRepository` (755c060b). This addresses a gap in `SitemapController` introduced by the new lazy-loading project (#111). --- .../OnTopic.AspNetCore.Mvc.IntegrationTests.Host.csproj | 1 + .../SampleActivator.cs | 8 +++++--- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/OnTopic.AspNetCore.Mvc.IntegrationTests.Host.csproj b/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/OnTopic.AspNetCore.Mvc.IntegrationTests.Host.csproj index dce9490f..9a2a4121 100644 --- a/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/OnTopic.AspNetCore.Mvc.IntegrationTests.Host.csproj +++ b/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/OnTopic.AspNetCore.Mvc.IntegrationTests.Host.csproj @@ -8,6 +8,7 @@ + diff --git a/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/SampleActivator.cs b/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/SampleActivator.cs index 1efd6b93..08be4215 100644 --- a/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/SampleActivator.cs +++ b/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/SampleActivator.cs @@ -8,11 +8,11 @@ using Microsoft.AspNetCore.Mvc.ViewComponents; using OnTopic.AspNetCore.Mvc.Controllers; using OnTopic.AspNetCore.Mvc.IntegrationTests.Areas.Area.Controllers; -using OnTopic.AspNetCore.Mvc.IntegrationTests.Host.Repositories; using OnTopic.Data.Caching; using OnTopic.Lookup; using OnTopic.Mapping; using OnTopic.Mapping.Hierarchical; +using OnTopic.TestDoubles; using OnTopic.ViewModels; namespace OnTopic.AspNetCore.Mvc.IntegrationTests.Host; @@ -33,6 +33,7 @@ public class SampleActivator : IControllerActivator, IViewComponentActivator { private readonly ITypeLookupService _typeLookupService; private readonly ITopicMappingService _topicMappingService; private readonly ITopicRepository _topicRepository; + private readonly ISitemapTopicRepository _sitemapTopicRepository; /*============================================================================================================================ | HIERARCHICAL TOPIC MAPPING SERVICE @@ -55,7 +56,7 @@ public SampleActivator() { /*-------------------------------------------------------------------------------------------------------------------------- | Initialize Topic Repository \-------------------------------------------------------------------------------------------------------------------------*/ - var sqlTopicRepository = new StubTopicRepository(); + var sqlTopicRepository = new Repositories.StubTopicRepository(); var cachedTopicRepository = new CachedTopicRepository(sqlTopicRepository); _ = new PageTopicViewModel(); @@ -63,6 +64,7 @@ public SampleActivator() { | Preload repository \-------------------------------------------------------------------------------------------------------------------------*/ _topicRepository = cachedTopicRepository; + _sitemapTopicRepository = new StubSitemapTopicRepository(_topicRepository); _typeLookupService = new DynamicTopicViewModelLookupService(); _topicMappingService = new TopicMappingService(_topicRepository, _typeLookupService); _ = _topicRepository.Load().GetAwaiter().GetResult(); @@ -111,7 +113,7 @@ public object Create(ControllerContext context) { nameof(ControllerController) => new ControllerController(), nameof(SitemapController) => - new SitemapController(_topicRepository), + new SitemapController(_sitemapTopicRepository), nameof(RedirectController) => new RedirectController(_topicRepository), _ => throw new InvalidOperationException($"Unknown controller {type.Name}") From 966d5c7b8fbf304b1b815668cb628cfec641492d Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Thu, 16 Jul 2026 20:33:40 -0700 Subject: [PATCH 196/337] Integrate `StubSitemapTopicRepository` with tests This updates the `SitemapControllerTest` to reflect the `SitemapController`'s new dependency (c0a919ee) on `ISitemapTopicRepository` (f9aa14d2), using the new `StubSitemapTopicRepository` (755c060b), which is now setup for dependency injection in the `SampleActivator` (79ec7a69). As part of this, I also updated the signatures to reflect the removal of the `includeMetadata` parameter (c1992034) as well as the two implicated tests for the `Extended()` format. This contributes to testing of the `ISitemapTopicRepository` (f9aa14d2) and `SitemapController` (c0a919ee), and is loosely associated with the lazy-loading testing (#111) in that this addresses a gap left by lazy-loading with the sitemap. --- .../SitemapControllerTest.cs | 83 +++---------------- 1 file changed, 13 insertions(+), 70 deletions(-) diff --git a/OnTopic.AspNetCore.Mvc.Tests/SitemapControllerTest.cs b/OnTopic.AspNetCore.Mvc.Tests/SitemapControllerTest.cs index d4597e9e..181c7dc5 100644 --- a/OnTopic.AspNetCore.Mvc.Tests/SitemapControllerTest.cs +++ b/OnTopic.AspNetCore.Mvc.Tests/SitemapControllerTest.cs @@ -1,4 +1,4 @@ -/*============================================================================================================================== +/*============================================================================================================================== | Author Ignia, LLC | Client Ignia, LLC | Project Topics Library @@ -11,6 +11,7 @@ using OnTopic.AspNetCore.Mvc.Tests.TestDoubles; using OnTopic.Data.Caching; using OnTopic.Repositories; +using OnTopic.TestDoubles; namespace OnTopic.Tests; @@ -26,7 +27,7 @@ public class SitemapControllerTest: IClassFixture { /*============================================================================================================================ | PRIVATE VARIABLES \---------------------------------------------------------------------------------------------------------------------------*/ - readonly ITopicRepository _topicRepository; + readonly ISitemapTopicRepository _topicRepository; readonly ControllerContext _context; /*============================================================================================================================ @@ -37,7 +38,8 @@ public class SitemapControllerTest: IClassFixture { /// /// /// This uses the to provide data, and then to - /// manage the in-memory representation of the data. While this introduces some overhead to the tests, the latter is a + /// manage the in-memory representation of the data, wrapped in a to satisfy the + /// 's narrower dependency. While this introduces some overhead to the tests, the latter is a /// relatively lightweight façade to any , and prevents the need to duplicate logic for /// crawling the object graph. In addition, it initializes a shared reference to use for the various /// tests. @@ -47,7 +49,7 @@ public SitemapControllerTest(TestTopicRepository topicRepository) { /*-------------------------------------------------------------------------------------------------------------------------- | Establish dependencies \-------------------------------------------------------------------------------------------------------------------------*/ - _topicRepository = new CachedTopicRepository(topicRepository); + _topicRepository = new StubSitemapTopicRepository(new CachedTopicRepository(topicRepository)); /*-------------------------------------------------------------------------------------------------------------------------- | Establish view model context @@ -70,7 +72,7 @@ public SitemapControllerTest(TestTopicRepository topicRepository) { | TEST: SITEMAP CONTROLLER: INDEX: RETURNS SITEMAP XML \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Triggers the index action of the action. + /// Triggers the index action of the action. /// [Fact] public void SitemapController_Index_ReturnsSitemapXml() { @@ -94,7 +96,7 @@ public void SitemapController_Index_ReturnsSitemapXml() { | TEST: SITEMAP CONTROLLER: INDEX: EXCLUDES CONTENT TYPES \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Triggers the index action of the action and verifies that it + /// Triggers the index action of the action and verifies that it /// properly excludes List content types, and skips over Container and PageGroup. /// [Fact] @@ -103,7 +105,7 @@ public void SitemapController_Index_ExcludesContentTypes() { var controller = new SitemapController(_topicRepository) { ControllerContext = new(_context) }; - var result = controller.Extended(true) as ContentResult; + var result = controller.Index(true) as ContentResult; var model = result?.Content as string; controller.Dispose(); @@ -125,7 +127,7 @@ public void SitemapController_Index_ExcludesContentTypes() { | TEST: SITEMAP CONTROLLER: INDEX: EXCLUDES CONTAINER DESCENDANTS \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Triggers the index action of the action and verifies that it + /// Triggers the index action of the action and verifies that it /// properly excludes the children of Container topics that are marked as NoIndex. /// [Fact] @@ -134,7 +136,7 @@ public void SitemapController_Index_ExcludesContainerDescendants() { var controller = new SitemapController(_topicRepository) { ControllerContext = new(_context) }; - var result = controller.Extended(true) as ContentResult; + var result = controller.Index(true) as ContentResult; var model = result?.Content as string; controller.Dispose(); @@ -149,7 +151,7 @@ public void SitemapController_Index_ExcludesContainerDescendants() { | TEST: SITEMAP CONTROLLER: INDEX: EXCLUDES PRIVATE BRANCHES \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Triggers the index action of the action and verifies that it + /// Triggers the index action of the action and verifies that it /// properly excludes the topics that are marked as IsPrivateBranch, including their descendants. /// [Fact] @@ -158,7 +160,7 @@ public void SitemapController_Index_ExcludesPrivateBranches() { var controller = new SitemapController(_topicRepository) { ControllerContext = new(_context) }; - var result = controller.Extended(true) as ContentResult; + var result = controller.Index(true) as ContentResult; var model = result?.Content as string; controller.Dispose(); @@ -169,63 +171,4 @@ public void SitemapController_Index_ExcludesPrivateBranches() { } - /*============================================================================================================================ - | TEST: SITEMAP CONTROLLER: EXTENDED: INCLUDES ATTRIBUTES - \---------------------------------------------------------------------------------------------------------------------------*/ - /// - /// Triggers the extended action of the action and ensures that the - /// results include the expected attributes. - /// - [Fact] - public void SitemapController_Extended_IncludesAttributes() { - - var controller = new SitemapController(_topicRepository) { - ControllerContext = new(_context) - }; - var result = controller.Extended(true) as ContentResult; - var model = result?.Content as string; - - controller.Dispose(); - - Assert.NotNull(model); - - Assert.Contains("", model, StringComparison.Ordinal); - Assert.Contains("/Web/Valid/Child/", model, StringComparison.Ordinal); - - Assert.Contains("Value", model, StringComparison.Ordinal); - Assert.Contains("Title", model, StringComparison.Ordinal); - Assert.Contains("", model, StringComparison.Ordinal); - Assert.Contains("Web:Redirect", model, StringComparison.Ordinal); - Assert.Contains("", model, StringComparison.Ordinal); - Assert.Contains("Web:Redirect", model, StringComparison.Ordinal); - - } - - /*============================================================================================================================ - | TEST: SITEMAP CONTROLLER: EXTENDED: EXCLUDES ATTRIBUTES - \---------------------------------------------------------------------------------------------------------------------------*/ - /// - /// Triggers the index action of the action and verifies that it - /// properly excludes e.g. the Body and IsHidden attributes. - /// - [Fact] - public void SitemapController_Index_ExcludesAttributes() { - - var controller = new SitemapController(_topicRepository) { - ControllerContext = new(_context) - }; - var result = controller.Extended(true) as ContentResult; - var model = result?.Content as string; - - controller.Dispose(); - - Assert.NotNull(model); - - Assert.False(model!.Contains("", StringComparison.Ordinal)); - Assert.False(model!.Contains("", StringComparison.Ordinal)); - Assert.False(model!.Contains("", StringComparison.Ordinal)); - Assert.False(model!.Contains("List", StringComparison.Ordinal)); - - } - } //Class \ No newline at end of file From 6ae375ee5c9f626c4b93ac2df07610a34a1a7c3b Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 17 Jul 2026 01:53:20 -0700 Subject: [PATCH 197/337] Fixed offset to avoid collisions (cont.) Fixed bugs in tests related to the fix of offset collisions (4f11cf8f) missed in the initial implementations. We got rid of the zero index, so all IDs and keys should start with 1, not 0. --- .../TopicRepositoryExtensionsTest.cs | 6 +++--- OnTopic.AspNetCore.Mvc.Tests/TopicViewComponentTest.cs | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/OnTopic.AspNetCore.Mvc.Tests/TopicRepositoryExtensionsTest.cs b/OnTopic.AspNetCore.Mvc.Tests/TopicRepositoryExtensionsTest.cs index e4295339..e819efba 100644 --- a/OnTopic.AspNetCore.Mvc.Tests/TopicRepositoryExtensionsTest.cs +++ b/OnTopic.AspNetCore.Mvc.Tests/TopicRepositoryExtensionsTest.cs @@ -51,16 +51,16 @@ public TopicRepositoryExtensionsTest(StubTopicRepository topicRepository) { public async Task Load_ByRoute_ReturnsTopic() { var routes = new RouteData(); - var topic = await _topicRepository.Load("Root:Web:Web_0:Web_0_1:Web_0_1_1"); + var topic = await _topicRepository.Load("Root:Web:Web_1:Web_1_1:Web_1_1_1"); routes.Values.Add("rootTopic", "Web"); - routes.Values.Add("path", "Web_0/Web_0_1/Web_0_1_1"); + routes.Values.Add("path", "Web_1/Web_1_1/Web_1_1_1"); var currentTopic = _topicRepository.Load(routes); Assert.NotNull(currentTopic); Assert.Equal(topic, currentTopic); - Assert.Equal("Web_0_1_1", currentTopic?.Key); + Assert.Equal("Web_1_1_1", currentTopic?.Key); } diff --git a/OnTopic.AspNetCore.Mvc.Tests/TopicViewComponentTest.cs b/OnTopic.AspNetCore.Mvc.Tests/TopicViewComponentTest.cs index 3aa4471a..03fbf9ce 100644 --- a/OnTopic.AspNetCore.Mvc.Tests/TopicViewComponentTest.cs +++ b/OnTopic.AspNetCore.Mvc.Tests/TopicViewComponentTest.cs @@ -214,7 +214,7 @@ public async Task PageLevelNavigation_Invoke_ReturnsNavigationViewModel() { [Fact] public async Task PageLevelNavigation_Invoke_ReturnsNull() { - var webPath = "/Web/Web_1/Web_1_0/"; + var webPath = "/Web/Web_1/Web_1_1/"; var viewComponent = new PageLevelNavigationViewComponent(_topicRepository, _hierarchicalMappingService) { ViewComponentContext = GetViewComponentContext(webPath) From cbf8aaba3297409530d15b2ca159f10463f95c97 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 17 Jul 2026 13:19:35 -0700 Subject: [PATCH 198/337] Added default output caching policy for sitemap MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The `SitemapController` (c0a919ee) and its underlying `ISitemapTopicRepository` (c0a919ee)—e.g., `SqlSitemapTopicRepository` (3b81cf1e) load a sparse but full-depth version of the topic graph every call. That's lighter than loading and caching even the whole indexed topic graph, but still a heavy I/O operation. Live data suggests sitemaps, even on low-traffic sites, get pinged every 5-10 minutes. So the expectation is that the data will be loaded once, transformed into XML, and then cached for a specified time. The new `CacheOutput()` this introduces scaffolds that. It sets a default period of one hour, and varies by hostname (for multisite setups), query string, and scheme (e.g., HTTP vs. HTTPS). The hostname and schema are important to make sure that a request on the non-canonical site doesn't pollute the cached results for the canonical site. The expiration can be set by passing the new `cacheDuration` to the `MapTopicSitemap()` extension. This doesn't actually do anything unless the cache is configured for the endpoint. That is on the responsibility of callers. A subsequent commit will provide a sample of that in the `Host` configuration. This addresses a gap in `SitemapController` introduced by the new lazy-loading project (#111). --- .../ServiceCollectionExtensions.cs | 38 ++++++++++++++++--- 1 file changed, 32 insertions(+), 6 deletions(-) diff --git a/OnTopic.AspNetCore.Mvc/ServiceCollectionExtensions.cs b/OnTopic.AspNetCore.Mvc/ServiceCollectionExtensions.cs index f1679882..5d7587bf 100644 --- a/OnTopic.AspNetCore.Mvc/ServiceCollectionExtensions.cs +++ b/OnTopic.AspNetCore.Mvc/ServiceCollectionExtensions.cs @@ -6,6 +6,7 @@ using Microsoft.AspNetCore.Builder; using Microsoft.AspNetCore.Mvc.Infrastructure; using Microsoft.AspNetCore.Mvc.TagHelpers; +using Microsoft.AspNetCore.OutputCaching; using Microsoft.AspNetCore.Routing; using Microsoft.Extensions.DependencyInjection; using Microsoft.Extensions.DependencyInjection.Extensions; @@ -239,19 +240,44 @@ public static ControllerActionEndpointConventionBuilder MapTopicErrors( | EXTENSION: MAP TOPIC SITEMAP (IENDPOINTROUTEBUILDER) \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Adds the Sitemap/{action=Index} endpoint route for the OnTopic sitemap. + /// Adds the Sitemap/{action=Index} endpoint route for the OnTopic sitemap, with a default server-side output + /// caching policy. /// /// - /// For most implementations, this will be covered by the default route, such as that implemented by the standard method that ships - /// with ASP.NET. This extension method is provided as a convenience method for implementations that aren't using the - /// standard route, for whatever reason, and want a specific route setup for the sitemap. + /// + /// For most implementations, this will be covered by the default route, such as that implemented by the standard method that ships + /// with ASP.NET. This extension method is provided as a convenience method for implementations that aren't using the + /// standard route, for whatever reason, and want a specific route setup for the sitemap. + /// + /// + /// The output caching policy is inert until the host also registers and calls + /// . Without that, the sitemap + /// still renders correctly on every request via the dedicated , but it isn't cached. + /// + /// + /// The policy varies by host and scheme, in addition to the indent query parameter, since renders every <loc> from the requesting host and scheme; without this, a deployment + /// serving multiple hosts (e.g., apex and www), or redirecting HTTP to HTTPS, could serve one host's cached URLs + /// to another. + /// /// - public static ControllerActionEndpointConventionBuilder MapTopicSitemap(this IEndpointRouteBuilder routes) => + /// The this route is being added to. + /// The duration to cache the rendered sitemap for. Defaults to sixty minutes. + public static ControllerActionEndpointConventionBuilder MapTopicSitemap( + this IEndpointRouteBuilder routes, + TimeSpan? cacheDuration = null + ) => routes.MapControllerRoute( name: "TopicSitemap", pattern: "Sitemap/{action=Index}", defaults: new { controller = "Sitemap" } + ).CacheOutput(policy => policy + .Expire(cacheDuration?? TimeSpan.FromMinutes(60)) + .SetVaryByHost(true) + .SetVaryByQuery("indent") + .VaryByValue(context => new("scheme", context.Request.Scheme)) ); /*============================================================================================================================ From a188249315be713218b2c78f5c860e367cc6b0ae Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 17 Jul 2026 13:21:32 -0700 Subject: [PATCH 199/337] Established output caching for sitemap in `Host` This ensures that output caching is available for the the default output cache policy on the `MapTopicSitemap()` extension method (cbf8aaba) to take advantage of. Callers that wish to take advantage of output caching on the sitemap (highly recommended!) must utilize this. --- OnTopic.AspNetCore.Mvc.Host/Program.cs | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/OnTopic.AspNetCore.Mvc.Host/Program.cs b/OnTopic.AspNetCore.Mvc.Host/Program.cs index b2498e34..3b828e55 100644 --- a/OnTopic.AspNetCore.Mvc.Host/Program.cs +++ b/OnTopic.AspNetCore.Mvc.Host/Program.cs @@ -26,10 +26,18 @@ }); /*------------------------------------------------------------------------------------------------------------------------------ -| Configure: Output Caching +| Configure: Response Caching \-----------------------------------------------------------------------------------------------------------------------------*/ builder.Services.AddResponseCaching(); +/*------------------------------------------------------------------------------------------------------------------------------ +| Configure: Output Caching +>------------------------------------------------------------------------------------------------------------------------------- +| Required for MapTopicSitemap()'s default caching policy to take effect; without this, the sitemap still renders correctly on +| every request via the dedicated SqlSitemapTopicRepository, but it isn't cached. +\-----------------------------------------------------------------------------------------------------------------------------*/ +builder.Services.AddOutputCache(); + /*------------------------------------------------------------------------------------------------------------------------------ | Configure: MVC \-----------------------------------------------------------------------------------------------------------------------------*/ @@ -74,6 +82,7 @@ app.UseRouting(); app.UseCors("default"); app.UseResponseCaching(); +app.UseOutputCache(); /*------------------------------------------------------------------------------------------------------------------------------ | Configure: MVC From db8fbe8302a8c7639943596d0b46236222dc4f62 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 17 Jul 2026 14:58:53 -0700 Subject: [PATCH 200/337] Established unit tests for lazy-loading repository I previously established a new `LazyLoadingTopicRepository` (f93a982c) as part of the lazy-loading infrastructure (#111) and moved a number of shared methods there, such as `StampResolver()` (70005a1a), `StampAscendants()` (29969d1c), `ResolveDeferredAssociations()` (b787626b), and moved stamping internally to that class via event handlers (cd215974). This establishes the tests that are specific to that base class, in conjunction with related classes in e.g., `TopicRepositoryBaseTest` (60276b84). --- .../LazyLoadingTopicRepositoryTest.cs | 758 ++++++++++++++++++ 1 file changed, 758 insertions(+) create mode 100644 OnTopic.Tests/LazyLoadingTopicRepositoryTest.cs diff --git a/OnTopic.Tests/LazyLoadingTopicRepositoryTest.cs b/OnTopic.Tests/LazyLoadingTopicRepositoryTest.cs new file mode 100644 index 00000000..303e2707 --- /dev/null +++ b/OnTopic.Tests/LazyLoadingTopicRepositoryTest.cs @@ -0,0 +1,758 @@ +/*============================================================================================================================== +| Author Ignia, LLC +| Client Ignia, LLC +| Project Topics Library +\=============================================================================================================================*/ +using OnTopic.Data.Caching; +using OnTopic.Repositories; +using OnTopic.TestDoubles.LazyLoading; +using Xunit; + +namespace OnTopic.Tests; + +/*============================================================================================================================== +| CLASS: LAZY LOADING TOPIC REPOSITORY TESTS +\-----------------------------------------------------------------------------------------------------------------------------*/ +/// +/// Provides unit tests for the store-independent, lazy-loading , evaluated through +/// the , a lazy test double that serves shallow topics from a flat, SQL-free +/// record store and loads each property on demand. +/// +/// +/// +/// is a standalone , never wrapped by a +/// . This matters: Were it wrapped in e.g., 's +/// shared field pattern, then , which is raised whenever the double builds a +/// topic for the first time, whether requested directly against the inner repository or through the decorator, would +/// synchronously re-enter the outer cache's handler, restamping that topic's as the +/// cache rather than the double itself. That would silently reroute every autoloading getter to , which delegates children and extended attributes to the inner resolver but +/// withholds relationships and references, resolving them itself via LoadDeferredAssociations instead. The double's +/// own fetch-count spy would then never see association fetches. So the standalone-mechanism tests (groups A through G, and +/// J) use , while the decorator-specific tests (groups H and I) use , which wraps its own, separate instance. +/// +/// +/// Both repositories share the same built-in seed dataset (see 's default +/// constructor): A four-level Root:Web content subtree of Web, Web_0, Web_0_0 (carrying an +/// extended attribute), Web_0_0_0, plus a sibling Web_1, with a resolvable relationship and reference pair +/// (Web_1, Web_0_0 / Web_0) and a stale, unresolvable pair (Web_0, a nonexistent target). +/// +/// +[ExcludeFromCodeCoverage] +public class LazyLoadingTopicRepositoryTest { + + /*============================================================================================================================ + | PRIVATE VARIABLES + \---------------------------------------------------------------------------------------------------------------------------*/ + readonly StubLazyLoadingTopicRepository _loadingTopicRepository; + readonly CachedTopicRepository _cachedTopicRepository; + + /*============================================================================================================================ + | PROPERTY: CANCELLATION TOKEN + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Shorthand for 's . + /// + private static CancellationToken CancellationToken => TestContext.Current.CancellationToken; + + /*============================================================================================================================ + | CONSTRUCTOR + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Initializes a new instance of the with two independent repositories: A + /// standalone for evaluating the repository directly, and a second, separate + /// instance wrapped by a for evaluating decorator-specific behavior. + /// + public LazyLoadingTopicRepositoryTest() { + _loadingTopicRepository = new(); + _cachedTopicRepository = new(new StubLazyLoadingTopicRepository()); + } + + /*============================================================================================================================ + | A: GENUINE DEFERRAL ON LOAD + \---------------------------------------------------------------------------------------------------------------------------*/ + + /*============================================================================================================================ + | TEST: LOAD: DEFAULT PAYLOAD: CHILDREN NOT LOADED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Loads a topic with the default payload and confirms its property is genuinely absent: Not + /// merely flagged , but backed by an empty collection. + /// + [Fact] + public async Task Load_DefaultPayload_ChildrenNotLoaded() { + + var topic = await _loadingTopicRepository.Load("Root:Web"); + + Assert.False(((ITopicLazyLoadable)topic!).IsLoaded(TopicPayload.Children)); + Assert.Empty(((ITopicBackingAccessor)topic).Children); + + } + + /*============================================================================================================================ + | TEST: LOAD: DEFAULT PAYLOAD: EXTENDED ATTRIBUTES NOT LOADED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Loads a topic with an extended attribute and confirms the extended-attribute boundary is genuinely absent: The attribute + /// value itself is missing from the backing collection, not merely flagged. + /// + [Fact] + public async Task Load_DefaultPayload_ExtendedAttributesNotLoaded() { + + var topic = await _loadingTopicRepository.Load("Root:Web:Web_0:Web_0_0"); + + Assert.False(((ITopicLazyLoadable)topic!).IsLoaded(TopicPayload.ExtendedAttributes)); + Assert.False(topic.Attributes.Contains("Body")); + + } + + /*============================================================================================================================ + | TEST: LOAD: DEFAULT PAYLOAD: ASSOCIATIONS DEFERRED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Loads a topic with both a relationship and a reference and confirms both association properties are , with genuine DeferredAssociation entries recorded, not resolved targets. + /// + [Fact] + public async Task Load_DefaultPayload_AssociationsDeferred() { + + var topic = await _loadingTopicRepository.Load("Root:Web:Web_1"); + var rawTopic = (ITopicBackingAccessor)topic!; + + Assert.False(((ITopicLazyLoadable)topic!).IsLoaded(TopicPayload.Relationships)); + Assert.False(((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.References)); + Assert.NotEmpty(rawTopic.Relationships.Deferred); + Assert.NotEmpty(rawTopic.References.Deferred); + + } + + /*============================================================================================================================ + | B: ON-DEMAND MATERIALIZATION VIA THE AUTOLOADING GETTERS + \---------------------------------------------------------------------------------------------------------------------------*/ + + /*============================================================================================================================ + | TEST: CHILDREN: NOT LOADED: MATERIALIZES REAL CHILDREN + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Touches on a topic whose children are and confirms the + /// getter returns the actual child topics from the record store, not an empty collection with a flipped flag. + /// + [Fact] + public async Task Children_NotLoaded_MaterializesRealChildren() { + + var topic = await _loadingTopicRepository.Load("Root:Web"); + var children = topic!.Children; + + Assert.Equal(2, children.Count); + Assert.Contains(children, child => child.Key == "Web_0"); + Assert.Contains(children, child => child.Key == "Web_1"); + + } + + /*============================================================================================================================ + | TEST: RELATIONSHIPS: NOT LOADED: MATERIALIZES TARGETS + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Touches on a topic with a resolvable relationship target and confirms the getter + /// connects the real target object. + /// + [Fact] + public async Task Relationships_NotLoaded_MaterializesTargets() { + + var topic = await _loadingTopicRepository.Load("Root:Web:Web_1"); + var related = topic!.Relationships.GetValues("Related"); + + Assert.Single(related); + Assert.Equal("Web_0_0", related[0].Key); + + } + + /*============================================================================================================================ + | TEST: REFERENCES: NOT LOADED: MATERIALIZES TARGETS + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Touches on a topic with a resolvable reference target and confirms the getter lazy loads + /// the target object. + /// + [Fact] + public async Task References_NotLoaded_MaterializesTargets() { + + var topic = await _loadingTopicRepository.Load("Root:Web:Web_1"); + + Assert.True(topic!.References.Contains("BaseTopic")); + Assert.Equal("Web_0", topic.References["BaseTopic"].Value?.Key); + + } + + /*============================================================================================================================ + | C: ON-DEMAND MATERIALIZATION VIA ASYNC ENSURE LOADED + \---------------------------------------------------------------------------------------------------------------------------*/ + + /*============================================================================================================================ + | TEST: ENSURE LOADED: CHILDREN: MATERIALIZES BEFORE ACCESS + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Awaits for , then + /// confirms the boundary is already and backed by real data before the getter is touched. + /// + [Fact] + public async Task EnsureLoaded_Children_MaterializesBeforeAccess() { + + var topic = await _loadingTopicRepository.Load("Root:Web"); + + await ((ITopicLazyLoadable)topic!).EnsureLoaded(TopicPayload.Children, cancellationToken: CancellationToken); + + Assert.True(((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.Children)); + Assert.Equal(2, ((ITopicBackingAccessor)topic).Children.Count); + + } + + /*============================================================================================================================ + | TEST: ENSURE LOADED: EXTENDED ATTRIBUTES: MATERIALIZES REAL VALUE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Awaits for and confirms the extended attribute getter returns the real value from the record + /// store, not merely a flipped . This is a distinct autoload seam from + /// and the association getters: It lives in AttributeCollection.GetValue, not directly on a + /// property getter. + /// + [Fact] + public async Task EnsureLoaded_ExtendedAttributes_MaterializesRealValue() { + + var topic = await _loadingTopicRepository.Load("Root:Web:Web_0:Web_0_0"); + + await ((ITopicLazyLoadable)topic!).EnsureLoaded(TopicPayload.ExtendedAttributes, cancellationToken: CancellationToken); + + Assert.True(((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.ExtendedAttributes)); + Assert.Equal("Extended body content for Web_0_0.", topic.Attributes.GetValue("Body")); + + } + + /*============================================================================================================================ + | D: FETCH-ONCE (SPY) + \---------------------------------------------------------------------------------------------------------------------------*/ + + /*============================================================================================================================ + | TEST: CHILDREN: ACCESSED TWICE: FETCHES ONCE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Touches twice and confirms the record store is only fetched once, via the double's + /// per-topic, per-property fetch-count spy. + /// + [Fact] + public async Task Children_AccessedTwice_FetchesOnce() { + + var topic = await _loadingTopicRepository.Load("Root:Web"); + + _ = topic!.Children; + _ = topic.Children; + + Assert.Equal(1, _loadingTopicRepository.GetFetchCount(topic.Id, TopicPayload.Children)); + + } + + /*============================================================================================================================ + | TEST: ENSURE LOADED: ALREADY LOADED: DOES NOT FETCH + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Loads a topic with children already requested, then calls again for the property payload, and + /// confirms no additional fetch is recorded. + /// + [Fact] + public async Task EnsureLoaded_AlreadyLoaded_DoesNotFetch() { + + var topic = await _loadingTopicRepository.Load("Root:Web", payload: TopicPayload.Children); + var fetchesAfterLoad = _loadingTopicRepository.TotalFetches; + + await ((ITopicLazyLoadable)topic!).EnsureLoaded(TopicPayload.Children, cancellationToken: CancellationToken); + + Assert.Equal(fetchesAfterLoad, _loadingTopicRepository.TotalFetches); + + } + + /*============================================================================================================================ + | E: RECURSIVE LAZY DESCENT + \---------------------------------------------------------------------------------------------------------------------------*/ + + /*============================================================================================================================ + | TEST: CHILDREN: MATERIALIZED CHILD: IS ITSELF LAZY + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Materializes the first level of a topic's children and confirms a materialized child reports its own children as , with no fetch yet recorded for that child, then touches the child's own and confirms a separate, later fetch materializes the next level. Proves that nothing trickles past + /// the level actually accessed. + /// + [Fact] + public async Task Children_MaterializedChild_IsItselfLazy() { + + var topic = await _loadingTopicRepository.Load("Root:Web"); + var web0 = topic!.Children["Web_0"]; + + Assert.False(((ITopicLazyLoadable)web0).IsLoaded(TopicPayload.Children)); + Assert.Equal(0, _loadingTopicRepository.GetFetchCount(web0.Id, TopicPayload.Children)); + + _ = web0.Children; + + Assert.Equal(1, _loadingTopicRepository.GetFetchCount(web0.Id, TopicPayload.Children)); + + } + + /*============================================================================================================================ + | F: RESOLVER STAMPING THROUGH THE PUBLIC PATH + \---------------------------------------------------------------------------------------------------------------------------*/ + + /*============================================================================================================================ + | TEST: LOAD: SERVED NODE: IS STAMPED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Loads a topic and confirms it carries a non-null , stamped through the public + /// /event path. + /// + [Fact] + public async Task Load_ServedNode_IsStamped() { + + var topic = await _loadingTopicRepository.Load("Root:Web"); + + Assert.NotNull(((ITopicLazyLoadable)topic!).Loader); + + } + + /*============================================================================================================================ + | TEST: CHILDREN: MATERIALIZED CHILDREN: ARE STAMPED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Loads children via and + /// confirms each child carries a non-null , which is what enables recursive lazy + /// loading (see ): The per-child OnTopicLoaded event raised + /// during materialization is what stamps them. + /// + [Fact] + public async Task Children_MaterializedChildren_AreStamped() { + + var topic = await _loadingTopicRepository.Load("Root:Web"); + + await ((ITopicLazyLoadable)topic!).EnsureLoaded(TopicPayload.Children, cancellationToken: CancellationToken); + + var children = ((ITopicBackingAccessor)topic).Children; + + Assert.Equal(2, children.Count); + + foreach (var child in children) { + Assert.NotNull(((ITopicLazyLoadable)child).Loader); + } + + } + + /*============================================================================================================================ + | TEST: LOAD: DEEP NODE: ASCENDANTS ARE STAMPED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Loads a deeply nested topic from a standalone repository and confirms that an ascendant, never itself the target of a + /// Load() call, is nonetheless stamped with an . + /// + [Fact] + public async Task Load_DeepNode_AscendantsAreStamped() { + + var topicRepository = new StubLazyLoadingTopicRepository(); + var topic = await topicRepository.Load("Root:Web:Web_0:Web_0_0:Web_0_0_0"); + var ascendant = topic?.Parent?.Parent; + + Assert.NotNull(ascendant); + Assert.NotNull((ascendant as ITopicLazyLoadable)?.Loader); + + } + + /*============================================================================================================================ + | TEST: LOAD: DEEP NODE: RELOAD IS IDEMPOTENT + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Reloads the same deep topic twice and confirms ascendants remain correctly stamped, with no spurious fetches triggered + /// by the second load, an indirect check of the ascendant-stamping's short-circuit correctness. + /// + [Fact] + public async Task Load_DeepNode_ReloadIsIdempotent() { + + var topicRepository = new StubLazyLoadingTopicRepository(); + var uniqueKey = "Root:Web:Web_0:Web_0_0:Web_0_0_0"; + + _ = await topicRepository.Load(uniqueKey); + + var fetchesAfterFirstLoad = topicRepository.TotalFetches; + var reloaded = await topicRepository.Load(uniqueKey); + + Assert.Equal(fetchesAfterFirstLoad, topicRepository.TotalFetches); + Assert.NotNull((reloaded?.Parent?.Parent as ITopicLazyLoadable)?.Loader); + + } + + /*============================================================================================================================ + | TEST: SAVE: NEW TOPIC: STAMPS RESOLVER + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Saves a new and confirms the repository stamps a onto it so that + /// deferred boundaries can be populated on demand after the save. + /// + [Fact] + public async Task Save_NewTopic_StampsResolver() { + + var parent = await _loadingTopicRepository.Load("Root:Web:Web_0:Web_0_0"); + var topic = new Topic("Test", "Page", parent); + + await _loadingTopicRepository.Save(topic); + + Assert.NotNull(((ITopicLazyLoadable)topic).Loader); + + } + + /*============================================================================================================================ + | G: FORCE-LOAD GATE (STAMPING MUST NOT FILL) + \---------------------------------------------------------------------------------------------------------------------------*/ + + /*============================================================================================================================ + | TEST: CHILDREN: MATERIALIZED: STAMPING DOES NOT LOAD GRANDCHILDREN + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Loads one level of children and confirms the loader-stamping pass triggered by each child's OnTopicLoaded event + /// does not, in turn, force-load its own children. Each child's own property is , so the gate at LazyLoadingTopicRepository.StampLoader, which only recurses into a + /// topic's already-loaded children, stamps the child without descending. Were the gate removed, StampLoader's + /// recursion would autoload every child's children, and the spy would show fetches for them; instead it shows none. + /// + [Fact] + public async Task Children_Materialized_StampingDoesNotLoadGrandchildren() { + + var topic = await _loadingTopicRepository.Load("Root:Web"); + var children = topic!.Children; + var web0 = children["Web_0"]; + var web1 = children["Web_1"]; + + Assert.Equal(1, _loadingTopicRepository.GetFetchCount(topic.Id, TopicPayload.Children)); + Assert.Equal(0, _loadingTopicRepository.GetFetchCount(web0.Id, TopicPayload.Children)); + Assert.Equal(0, _loadingTopicRepository.GetFetchCount(web1.Id, TopicPayload.Children)); + + } + + /*============================================================================================================================ + | H: DEFERRED-ASSOCIATION RESOLUTION THROUGH THE CACHE DECORATOR + \---------------------------------------------------------------------------------------------------------------------------*/ + + /*============================================================================================================================ + | TEST: ENSURE LOADED: STALE RELATIONSHIP TARGET: IS DISCARDED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Calls on a topic with a deferred relationship whose target is absent + /// from the underlying record store, and confirms the association resolves to nothing: The deferred entry is dropped, not + /// left dangling, while the property still ends up . + /// + [Fact] + public async Task EnsureLoaded_StaleRelationshipTarget_IsDiscarded() { + + var source = await _cachedTopicRepository.Load("Root:Web:Web_0"); + + await _cachedTopicRepository.EnsureLoaded(source!, TopicPayload.Relationships, cancellationToken: CancellationToken); + + Assert.Equal(LoadState.Loaded, source!.Relationships.LoadState); + Assert.Empty(source.Relationships.GetValues("Related")); + + } + + /*============================================================================================================================ + | TEST: ENSURE LOADED: STALE REFERENCE TARGET: IS DISCARDED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Calls on a topic with a deferred reference whose target is absent from + /// the underlying record store, and confirms the association resolves to nothing: The deferred entry is dropped, not left + /// dangling, while the property still ends up . + /// + [Fact] + public async Task EnsureLoaded_StaleReferenceTarget_IsDiscarded() { + + var source = await _cachedTopicRepository.Load("Root:Web:Web_0"); + + await _cachedTopicRepository.EnsureLoaded(source!, TopicPayload.References, cancellationToken: CancellationToken); + + Assert.Equal(LoadState.Loaded, source!.References.LoadState); + Assert.False(source.References.Contains("BaseTopic")); + + } + + /*============================================================================================================================ + | TEST: ENSURE LOADED: MISSING REFERENCE TARGET: RESOLVES AND CONNECTS + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Calls on a topic whose References.LoadState is NotLoaded, + /// confirming that the loader re-queries for the topic's references, loads a target initially absent from the cache, and + /// connects the edge. The reference-target complement to . + /// + [Fact] + public async Task EnsureLoaded_MissingReferenceTarget_ResolvesAndConnects() { + + // The cache seeds only Root and Root:Configuration; "Web" (id 10000) is initially absent from the cache + var root = (await _cachedTopicRepository.Load(-1))!; + ((ITopicBackingAccessor)root).References.Deferred.Add(new("_stub", 10000)); + + await _cachedTopicRepository.EnsureLoaded(root, TopicPayload.References, cancellationToken: CancellationToken); + + Assert.Equal(LoadState.Loaded, root.References.LoadState); + Assert.Equal(10000, root.References["_stub"].Value?.Id); + + } + + /*============================================================================================================================ + | I: DECORATOR STAMP PRECEDENCE + \---------------------------------------------------------------------------------------------------------------------------*/ + + /*============================================================================================================================ + | TEST: LOAD: DECORATED: OUTER RESOLVER WINS + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Loads a topic through a wrapping the lazy double and confirms the loaded topic's + /// is the outer cache instance, not the inner double, verifying the synchronous + /// re-entry described on LazyLoadingTopicRepository.OnTopicLoaded. + /// + [Fact] + public async Task Load_Decorated_OuterResolverWins() { + + var topic = await _cachedTopicRepository.Load("Root:Web"); + + Assert.Same(_cachedTopicRepository, ((ITopicLazyLoadable)topic!).Loader); + + } + + /*============================================================================================================================ + | J: EDGE CASES + \---------------------------------------------------------------------------------------------------------------------------*/ + + /*============================================================================================================================ + | TEST: ENSURE LOADED: NEW TOPIC: DOES NOT FETCH + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Calls directly against an in-memory + /// attached to nothing, and confirms no fetch is recorded. Distinct from the gating case covered in TopicTest, this + /// is asserted through the repository's own spy, not merely the absence of a resolver call. + /// + [Fact] + public async Task EnsureLoaded_NewTopic_DoesNotFetch() { + + var topic = new Topic("Test", "Page"); + + await _loadingTopicRepository.EnsureLoaded(topic, TopicPayload.Children, cancellationToken: CancellationToken); + + Assert.Equal(0, _loadingTopicRepository.TotalFetches); + + } + + /*============================================================================================================================ + | K: IN-GRAPH ASSOCIATION RESOLUTION + \---------------------------------------------------------------------------------------------------------------------------*/ + + /*============================================================================================================================ + | TEST: ENSURE LOADED: TARGETS RESIDENT IN GRAPH: RESOLVE AND CLEAR DEFERRED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Loads a target topic into the repository's graph ahead of time, then loads a second topic whose deferred relationship + /// and reference entries point at it, and confirms that connects both associations to the + /// in-graph instance and clears their Deferred entries, without either target needing to be (re)built from the + /// record store. + /// + [Fact] + public async Task EnsureLoaded_TargetsResidentInGraph_ResolveAndClearDeferred() { + + var web00 = await _loadingTopicRepository.Load("Root:Web:Web_0:Web_0_0"); + var web0 = web00!.Parent; + var topic = await _loadingTopicRepository.Load("Root:Web:Web_1"); + var rawTopic = (ITopicBackingAccessor)topic!; + + await ((ITopicLazyLoadable)topic!).EnsureLoaded( + TopicPayload.Relationships | TopicPayload.References, + cancellationToken: CancellationToken + ); + + var related = topic.Relationships.GetValues("Related"); + + Assert.Single(related); + Assert.Same(web00, related[0]); + Assert.Same(web0, topic.References["BaseTopic"].Value); + Assert.Empty(rawTopic.Relationships.Deferred); + Assert.Empty(rawTopic.References.Deferred); + + } + + /*============================================================================================================================ + | L: SUFFICIENCY-GATED CACHE HITS + \---------------------------------------------------------------------------------------------------------------------------*/ + + /*============================================================================================================================ + | TEST: LOAD: NARROW PAYLOAD HIT: TOPS UP AND CONVERGES + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Loads a topic with the default payload, then loads it again, non-recursively, requesting , and confirms the second call returns the exact same, resident instance, but now + /// filled with the extended attribute value, and not merely a flipped . + /// + [Fact] + public async Task Load_NarrowPayloadHit_TopsUpAndConverges() { + + var topic = await _cachedTopicRepository.Load("Root:Web:Web_0:Web_0_0"); + + Assert.False(((ITopicLazyLoadable)topic!).IsLoaded(TopicPayload.ExtendedAttributes)); + + var reloaded = await _cachedTopicRepository.Load( + "Root:Web:Web_0:Web_0_0", + topic, + false, + TopicPayload.ExtendedAttributes + ); + + Assert.Same(topic, reloaded); + Assert.True(((ITopicLazyLoadable)reloaded!).IsLoaded(TopicPayload.ExtendedAttributes)); + Assert.Equal("Extended body content for Web_0_0.", reloaded.Attributes.GetValue("Body")); + + } + + /*============================================================================================================================ + | TEST: LOAD: RECURSIVE HIT: CONVERGES SUBTREE THEN CLEAN HIT + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Loads a subtree recursively with the full payload, then repeats the identical call, and confirms the second call is a + /// genuine, converged hit: The same instance is returned and no further fetches are recorded against the underlying , proving converged on every resident descendant rather + /// than merely on the seed. + /// + [Fact] + public async Task Load_RecursiveHit_ConvergesSubtreeThenCleanHit() { + + var stub = new StubLazyLoadingTopicRepository(); + var cache = new CachedTopicRepository(stub); + var gate = TopicPayload.All & ~(TopicPayload.Relationships | TopicPayload.References); + + var seed = await cache.Load("Root:Web:Web_0", null, true, TopicPayload.All); + + Assert.True(((ITopicLazyLoadable)seed!).IsLoaded(gate, isRecursive: true)); + + var fetchesAfterFirstLoad = stub.TotalFetches; + var reloaded = await cache.Load("Root:Web:Web_0", null, true, TopicPayload.All); + + Assert.Same(seed, reloaded); + Assert.Equal(fetchesAfterFirstLoad, stub.TotalFetches); + + } + + /*============================================================================================================================ + | TEST: LOAD: RECURSIVE TOP UP ON RESIDENT SEED: ANCESTORS STAY NOT LOADED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Loads a deep, shallow seed, then tops it up recursively for and , and confirms the seed and its descendants converge while the seed's ascendant + /// remains , matching the parent plan distinction of ascendants vs. seed graph. + /// + [Fact] + public async Task Load_RecursiveTopUpOnResidentSeed_AncestorsStayNotLoaded() { + + var seed = await _cachedTopicRepository.Load("Root:Web:Web_0:Web_0_0"); + + Assert.False(((ITopicLazyLoadable)seed!).IsLoaded(TopicPayload.Children)); + + var deep = await _cachedTopicRepository.Load( + "Root:Web:Web_0:Web_0_0", + seed, + true, + TopicPayload.Children | TopicPayload.ExtendedAttributes + ); + + var ancestor = deep!.Parent; + + Assert.Same(seed, deep); + Assert.True( + ((ITopicLazyLoadable)deep).IsLoaded(TopicPayload.Children | TopicPayload.ExtendedAttributes, isRecursive: true) + ); + Assert.Equal("Extended body content for Web_0_0.", deep.Attributes.GetValue("Body")); + Assert.False(((ITopicLazyLoadable)ancestor!).IsLoaded(TopicPayload.Children)); + + } + + /*============================================================================================================================ + | TEST: LOAD: RECURSIVE TOP UP: IN-GRAPH CORE CONNECTS MERGED REGION + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Loads a topic with deferred relationship and reference targets that are not yet loaded, then recursively tops up its + /// shared ancestor so both targets are pulled into the same merged graph, and confirms the in-graph association are + /// correctly connected and clearing Deferred without a further round-trip dedicated to associations. + /// + [Fact] + public async Task Load_RecursiveTopUp_InGraphCoreConnectsMergedRegion() { + + var stub = new StubLazyLoadingTopicRepository(); + var cache = new CachedTopicRepository(stub); + + var topic = await cache.Load("Root:Web:Web_1"); + var rawTopic = (ITopicBackingAccessor)topic!; + + Assert.NotEmpty(rawTopic.Relationships.Deferred); + Assert.NotEmpty(rawTopic.References.Deferred); + + var web = await cache.Load("Root:Web", null, true, TopicPayload.Children); + var web00 = web!.Children["Web_0"].Children["Web_0_0"]; + var related = topic!.Relationships.GetValues("Related"); + + Assert.Single(related); + Assert.Same(web00, related[0]); + Assert.Equal("Web_0", topic.References["BaseTopic"].Value?.Key); + Assert.Empty(rawTopic.Relationships.Deferred); + Assert.Empty(rawTopic.References.Deferred); + + } + + /*============================================================================================================================ + | TEST: LOAD: WHOLE TREE TOP UP: MATERIALIZES THEN CLEAN HIT + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Seeds the cache with the default, shallow Root (, non-recursive), then requests + /// the whole tree recursively via the topicId < 0 branch, and confirms every descendant is materialized and , and that a third, identical call is a genuine, converged hit against the same instance with + /// no further fetches, thus exercising the 's own lazy Root boundary, + /// as per 's documented lazy defaults, alongside EnsureLoaded's whole-tree + /// branch. + /// + [Fact] + public async Task Load_WholeTreeTopUp_MaterializesThenCleanHit() { + + var stub = new StubLazyLoadingTopicRepository(); + var cache = new CachedTopicRepository(stub); + var gate = TopicPayload.All & ~(TopicPayload.Relationships | TopicPayload.References); + + var seed = await cache.Load(-1, null, false, TopicPayload.None); + + Assert.False(((ITopicLazyLoadable)seed!).IsLoaded(TopicPayload.Children)); + + var loaded = await cache.Load(-1, seed, true, TopicPayload.All); + + Assert.Same(seed, loaded); + Assert.True(((ITopicLazyLoadable)loaded!).IsLoaded(gate, isRecursive: true)); + + var web = loaded.Children["Web"]; + + Assert.True(web.Children.Contains("Web_0")); + Assert.True(web.Children.Contains("Web_1")); + Assert.True(web.Children["Web_0"].Children.Contains("Web_0_0")); + Assert.True(web.Children["Web_0"].Children["Web_0_0"].Children.Contains("Web_0_0_0")); + Assert.Equal( + "Extended body content for Web_0_0.", + web.Children["Web_0"].Children["Web_0_0"].Attributes.GetValue("Body") + ); + + var fetchesAfterLoad = stub.TotalFetches; + var reloaded = await cache.Load(-1, null, true, TopicPayload.All); + + Assert.Same(loaded, reloaded); + Assert.Equal(fetchesAfterLoad, stub.TotalFetches); + + } + +} //Class \ No newline at end of file From 92a99954cd2305d4ebdbe837dbeb035f5755c42e Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 17 Jul 2026 20:02:37 -0700 Subject: [PATCH 201/337] Allow `FindFirst()`, `FindAll()` past `NotLoaded` Previously, `FindFirst()` and `FindAll()` in the `TopicExtensions` were both gated by `Children.LoadState` of `NotLoaded` to avoid triggering a lazy load (4d83e0e1). Even once `ITopicLazyLoadable` were introduced, however, it kept that basic gate (248411ea), even though the underlying `ITopicBackingService` would allow it to safely step past a not fully loaded `Children`. This results in a lot of potential bugs; for instance, a `GetTopicIndex()` uses `FindAll()` to create the index, which is then used to connect new topics into the topic graph. But if a topic is loaded into the topic graph with ascendants, those ascendants' `Children` won't be `Loaded`, and therefore any such branches will be invisible to the index. This affects, in particular, `ResolveAssociates()` and `LoadDeferredAssociates()` (167067f3). This fixes that by simply accessing `Children` via the backing field (via `ITopicBackingAccessor`) as opposed to treating `Children` `NotLoaded` as a gate. This fixes a bug in my initial implementations of the lazy-loading infrastructure (#111). --- OnTopic/Querying/TopicExtensions.cs | 42 ++++++++++++++--------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/OnTopic/Querying/TopicExtensions.cs b/OnTopic/Querying/TopicExtensions.cs index 3e25859e..488bad18 100644 --- a/OnTopic/Querying/TopicExtensions.cs +++ b/OnTopic/Querying/TopicExtensions.cs @@ -19,8 +19,8 @@ namespace OnTopic.Querying; /// /// These extensions, while powerful, were intended to be used against fully loaded, in-memory topic trees. Their usefulness /// with lazy-loaded trees is limited and, potentially, even expensive, as innocent seeming queries may trigger lazy-loading -/// of attributes, relationships, references, children, &c. Children are gated in and , but the predicate parameter can easily call into any of these. +/// of attributes, relationships, references, children, etc. Traversal itself never triggers a load, as it reads directly, though the predicate parameter can easily call into any of these. /// public static class TopicExtensions { @@ -31,9 +31,11 @@ public static class TopicExtensions { /// Finds the first instance of a in the topic tree that satisfies the delegate. /// /// - /// When using this with a lazy-loaded tree, be aware that it may trigger costly on-demand loading of attributes, - /// relationships, references, and children if they're included in the . It is recommended to - /// avoid use with lazy-loaded trees, or to use extreme caution. + /// Traverses via , the non-triggering backing field, so this never directly + /// causes a lazy load. The is not similarly guarded, however: When using this with a + /// lazy-loaded tree, be aware that it may trigger costly on-demand loading of attributes, relationships, references, and + /// children if they're included in the predicate. It is recommended to avoid use with lazy-loaded trees, or to use extreme + /// caution. /// /// The instance of the to operate against; populated automatically by .NET. /// The function to validate whether a should be included in the output. @@ -56,12 +58,10 @@ public static class TopicExtensions { /*-------------------------------------------------------------------------------------------------------------------------- | Recurse over children \-------------------------------------------------------------------------------------------------------------------------*/ - if (((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.Children)) { - foreach (var child in topic.Children) { - var nestedResult = child.FindFirst(predicate); - if (nestedResult is not null) { - return nestedResult; - } + foreach (var child in ((ITopicBackingAccessor)topic).Children) { + var nestedResult = child.FindFirst(predicate); + if (nestedResult is not null) { + return nestedResult; } } @@ -128,9 +128,11 @@ public static class TopicExtensions { /// Retrieves a collection of topics based on a supplied function. /// /// - /// When using this with a lazy-loaded tree, be aware that it may trigger costly on-demand loading of attributes, - /// relationships, references, and children if they're included in the . It is recommended to - /// avoid use with lazy-loaded trees, or to use extreme caution. + /// Traverses via , the non-triggering backing field, so this never directly + /// causes a lazy load. The is not similarly guarded, however: When using this with a + /// lazy-loaded tree, be aware that it may trigger costly on-demand loading of attributes, relationships, references, and + /// children if they're included in the predicate. It is recommended to avoid use with lazy-loaded trees, or to use extreme + /// caution. /// /// The instance of the to operate against; populated automatically by .NET. /// The function to validate whether a should be included in the output. @@ -155,13 +157,11 @@ public static ReadOnlyTopicCollection FindAll(this Topic topic, Func Date: Fri, 17 Jul 2026 20:07:18 -0700 Subject: [PATCH 202/337] Fixed tests after `FindAll()`, `FindFirst()` fixes With the recent fixes to `FindAll()` and `FindFirst()` (92a99954), w now _expect_ a topic sitting below `IsLoaded(TopicPayload.Children)` to be found, and so the prior tests (7fa99cc8) need to be flipped to account for this. This patches the testing for #111. --- OnTopic.Tests/TopicQueryingTest.cs | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/OnTopic.Tests/TopicQueryingTest.cs b/OnTopic.Tests/TopicQueryingTest.cs index 0316125f..97b2a7d1 100644 --- a/OnTopic.Tests/TopicQueryingTest.cs +++ b/OnTopic.Tests/TopicQueryingTest.cs @@ -316,15 +316,16 @@ public void AnyNew_ContainsExisting_ReturnFalse() { } /*============================================================================================================================ - | TEST: FIND FIRST: NOT LOADED CHILD: DOES NOT DESCEND + | TEST: FIND FIRST: NOT LOADED CHILD: STILL FINDS RESIDENT DESCENDANT \---------------------------------------------------------------------------------------------------------------------------*/ /// /// Creates a three-level topic hierarchy and manually sets the middle topic's to . Verifies that stops at that node and does not return - /// the grandchild, which would only be reachable by descending into the not-loaded subtree. + /// "LoadState.NotLoaded"/> despite already having a grandchild (e.g., as left behind by an ancestor crawl or a partial + /// fill). Verifies that traverses via the non-triggering backing field and so still + /// finds the grandchild, rather than treating the stamp as if the branch were empty. /// [Fact] - public void FindFirst_WithNotLoadedChild_DoesNotDescend() { + public void FindFirst_WithNotLoadedChild_StillFindsResidentDescendant() { var parent = new Topic("Parent", "Page", null, 1); var child = new Topic("Child", "Page", parent, 2); @@ -334,20 +335,21 @@ public void FindFirst_WithNotLoadedChild_DoesNotDescend() { var result = parent.FindFirst(t => t == grandchild); - Assert.Null(result); + Assert.Equal(grandchild, result); } /*============================================================================================================================ - | TEST: FIND ALL: PARTIALLY LOADED GRAPH: EXCLUDES NOT LOADED SUBTREES + | TEST: FIND ALL: PARTIALLY LOADED GRAPH: INCLUDES RESIDENT NOT LOADED SUBTREES \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Creates a topic graph where one branch has a children collection. Verifies that includes the not-loaded node itself (it is resident) but excludes its - /// descendants, which are unreachable without triggering a load. + /// Creates a topic graph where one branch has a children collection despite already + /// having a grandchild (e.g., as left behind by an ancestor crawl or a partial fill). Verifies that traverses via the non-triggering backing field and so still returns the grandchild, + /// rather than treating the stamp as if the branch were empty. /// [Fact] - public void FindAll_WithPartiallyLoadedGraph_ExcludesNotLoadedSubtrees() { + public void FindAll_WithPartiallyLoadedGraph_IncludesResidentNotLoadedSubtrees() { var parent = new Topic("Parent", "Page", null, 1); var childA = new Topic("ChildA", "Page", parent, 2); @@ -363,7 +365,7 @@ public void FindAll_WithPartiallyLoadedGraph_ExcludesNotLoadedSubtrees() { Assert.Contains(childA, results); Assert.Contains(grandchildA, results); Assert.Contains(childB, results); - Assert.DoesNotContain(grandchildB, results); + Assert.Contains(grandchildB, results); } From 665e7f50f25397924d486aad79192816aaa4219c Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 17 Jul 2026 20:26:20 -0700 Subject: [PATCH 203/337] Improved lazy-load awareness of `Delete()` Previously, `TopicRepository.Delete()` checked to see if there were any children by calling `topic.Children.Any()` and thus triggering lazy loading unnecessarily. Now, it checks the `ITopicBackingAccessor` via `ITopicLazyLoadable`, but also relies on information from `LoadState` to determine if there are children, independent of whether any are loaded. (If `NotLoaded`, we know there are `Children`, even if `Count` is 0.) This fixes a limitation in the implementation of lazy-loading (#111) by potentially forcing `Delete()` to first load any children to determine if it can do a non-recursive delete. (The special pass for `List` is a preexisting decision, but one I'm not convinced of. It's basically saying Nested Topics won't get in the way. But that's just one way of identifying a nested topic. I'll maintain it for now. --- OnTopic/Repositories/TopicRepository.cs | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/OnTopic/Repositories/TopicRepository.cs b/OnTopic/Repositories/TopicRepository.cs index 6dc1bff6..77820781 100644 --- a/OnTopic/Repositories/TopicRepository.cs +++ b/OnTopic/Repositories/TopicRepository.cs @@ -583,8 +583,16 @@ public override sealed async Task Delete([ValidatedNotNull]Topic topic, bool isR /*-------------------------------------------------------------------------------------------------------------------------- | Validate descendants + >--------------------------------------------------------------------------------------------------------------------------- + | Reads Children via ITopicLazyLoadable, not the autoloading getter, so a lazy-loaded topic isn't forced to fetch its + | children merely to be deleted. Both signals are already definitive: An ITopicRepository only ever stamps Children as + | NotLoaded when the topic genuinely has children it hasn't fully fetched, so no count check is needed for that case. When + | Loaded, the resident Children collection is complete, so its count is authoritative. \-------------------------------------------------------------------------------------------------------------------------*/ - if (!isRecursive && topic.Children.Any(t => !t.ContentType.Equals("List", StringComparison.OrdinalIgnoreCase))) { + var rawTopic = (ITopicLazyLoadable)topic; + var hasResidentChildren = rawTopic.Children.Any(t => !t.ContentType.Equals("List", StringComparison.OrdinalIgnoreCase)); + + if (!isRecursive && (hasResidentChildren || !rawTopic.IsLoaded(TopicPayload.Children))) { throw new ReferentialIntegrityException( $"The topic '{topic.GetUniqueKey()}' cannot be deleted. It has child topics, but '{nameof(isRecursive)}' is set to " + $"false. To delete '{topic.GetUniqueKey()}' and all of its descendants, set '{nameof(isRecursive)}' to true." From 0202356012a1ccce2180d3c65f41b6120babec02 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 17 Jul 2026 20:36:19 -0700 Subject: [PATCH 204/337] Centralized `ITopicLazyLoadable` variable For each test that needs to access `ITopicLazyLoadable` (e.g., to get access to `IsLoaded()`) more than one, define e.g., `rawTopic` instead of casting `topic` multiple times inline. --- OnTopic.Tests/ITopicLazyLoadableTest.cs | 5 +- .../LazyLoadingTopicRepositoryTest.cs | 15 +++--- OnTopic.Tests/TopicRepositoryBaseTest.cs | 51 +++++++++++-------- 3 files changed, 42 insertions(+), 29 deletions(-) diff --git a/OnTopic.Tests/ITopicLazyLoadableTest.cs b/OnTopic.Tests/ITopicLazyLoadableTest.cs index 103f6e45..1c027d56 100644 --- a/OnTopic.Tests/ITopicLazyLoadableTest.cs +++ b/OnTopic.Tests/ITopicLazyLoadableTest.cs @@ -138,12 +138,13 @@ public void IsLoaded_NotLoadedChildren_ExcludedPayload_Recursive_ReturnsFalse() public void IsLoaded_NotLoadedChildren_NeverTriggersLoad() { var topic = new Topic("Test", "Page", null, 1); + var rawTopic = (ITopicLazyLoadable)topic; var loader = new TrackingTopicLazyLoader(); - ((ITopicLazyLoadable)topic).Loader = loader; + rawTopic.Loader = loader; topic.Children.LoadState = LoadState.NotLoaded; - var result = ((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.All, isRecursive: true); + var result = rawTopic.IsLoaded(TopicPayload.All, isRecursive: true); Assert.False(result); Assert.False(loader.WasCalled); diff --git a/OnTopic.Tests/LazyLoadingTopicRepositoryTest.cs b/OnTopic.Tests/LazyLoadingTopicRepositoryTest.cs index 303e2707..e260f4b3 100644 --- a/OnTopic.Tests/LazyLoadingTopicRepositoryTest.cs +++ b/OnTopic.Tests/LazyLoadingTopicRepositoryTest.cs @@ -119,9 +119,10 @@ public async Task Load_DefaultPayload_AssociationsDeferred() { var topic = await _loadingTopicRepository.Load("Root:Web:Web_1"); var rawTopic = (ITopicBackingAccessor)topic!; + var lazyTopic = (ITopicLazyLoadable)topic!; - Assert.False(((ITopicLazyLoadable)topic!).IsLoaded(TopicPayload.Relationships)); - Assert.False(((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.References)); + Assert.False(lazyTopic.IsLoaded(TopicPayload.Relationships)); + Assert.False(lazyTopic.IsLoaded(TopicPayload.References)); Assert.NotEmpty(rawTopic.Relationships.Deferred); Assert.NotEmpty(rawTopic.References.Deferred); @@ -200,10 +201,11 @@ public async Task References_NotLoaded_MaterializesTargets() { public async Task EnsureLoaded_Children_MaterializesBeforeAccess() { var topic = await _loadingTopicRepository.Load("Root:Web"); + var rawTopic = (ITopicLazyLoadable)topic!; - await ((ITopicLazyLoadable)topic!).EnsureLoaded(TopicPayload.Children, cancellationToken: CancellationToken); + await rawTopic.EnsureLoaded(TopicPayload.Children, cancellationToken: CancellationToken); - Assert.True(((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.Children)); + Assert.True(rawTopic.IsLoaded(TopicPayload.Children)); Assert.Equal(2, ((ITopicBackingAccessor)topic).Children.Count); } @@ -222,10 +224,11 @@ public async Task EnsureLoaded_Children_MaterializesBeforeAccess() { public async Task EnsureLoaded_ExtendedAttributes_MaterializesRealValue() { var topic = await _loadingTopicRepository.Load("Root:Web:Web_0:Web_0_0"); + var rawTopic = (ITopicLazyLoadable)topic!; - await ((ITopicLazyLoadable)topic!).EnsureLoaded(TopicPayload.ExtendedAttributes, cancellationToken: CancellationToken); + await rawTopic.EnsureLoaded(TopicPayload.ExtendedAttributes, cancellationToken: CancellationToken); - Assert.True(((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.ExtendedAttributes)); + Assert.True(rawTopic.IsLoaded(TopicPayload.ExtendedAttributes)); Assert.Equal("Extended body content for Web_0_0.", topic.Attributes.GetValue("Body")); } diff --git a/OnTopic.Tests/TopicRepositoryBaseTest.cs b/OnTopic.Tests/TopicRepositoryBaseTest.cs index 62fca05e..da754dc1 100644 --- a/OnTopic.Tests/TopicRepositoryBaseTest.cs +++ b/OnTopic.Tests/TopicRepositoryBaseTest.cs @@ -1188,11 +1188,12 @@ public async Task Save_NotLoadedChildren_SkipsRecursiveDescent() { public async Task EnsureLoaded_ExtendedAttributesNotLoaded_MarksLoaded() { var topic = await _topicRepository.Load(11111); + var rawTopic = (ITopicLazyLoadable)topic!; topic!.Attributes.LoadState = LoadState.NotLoaded; - await ((ITopicLazyLoadable)topic).EnsureLoaded(TopicPayload.ExtendedAttributes); + await rawTopic.EnsureLoaded(TopicPayload.ExtendedAttributes); - Assert.True(((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.ExtendedAttributes)); + Assert.True(rawTopic.IsLoaded(TopicPayload.ExtendedAttributes)); } @@ -1208,13 +1209,14 @@ public async Task EnsureLoaded_ExtendedAttributesNotLoaded_MarksLoaded() { public async Task EnsureLoaded_MixedBoundaries_SkipsLoadedBoundaries() { var topic = await _topicRepository.Load(11111); + var rawTopic = (ITopicLazyLoadable)topic!; topic!.Attributes.LoadState = LoadState.NotLoaded; - Assert.True(((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.Children)); - await ((ITopicLazyLoadable)topic).EnsureLoaded(TopicPayload.Children | TopicPayload.ExtendedAttributes); + Assert.True(rawTopic.IsLoaded(TopicPayload.Children)); + await rawTopic.EnsureLoaded(TopicPayload.Children | TopicPayload.ExtendedAttributes); - Assert.True(((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.ExtendedAttributes)); - Assert.True(((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.Children)); + Assert.True(rawTopic.IsLoaded(TopicPayload.ExtendedAttributes)); + Assert.True(rawTopic.IsLoaded(TopicPayload.Children)); } @@ -1236,11 +1238,12 @@ public async Task EnsureLoaded_MixedBoundaries_SkipsLoadedBoundaries() { public async Task EnsureLoaded_RelationshipsNotLoaded_MarksLoaded() { var topic = await _topicRepository.Load(11111); + var rawTopic = (ITopicLazyLoadable)topic!; topic!.Relationships.Deferred.Add(new("_stub", 11111)); - await ((ITopicLazyLoadable)topic).EnsureLoaded(TopicPayload.Relationships); + await rawTopic.EnsureLoaded(TopicPayload.Relationships); - Assert.True(((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.Relationships)); + Assert.True(rawTopic.IsLoaded(TopicPayload.Relationships)); } @@ -1262,11 +1265,12 @@ public async Task EnsureLoaded_RelationshipsNotLoaded_MarksLoaded() { public async Task EnsureLoaded_ReferencesNotLoaded_MarksLoaded() { var topic = await _topicRepository.Load(11111); + var rawTopic = (ITopicLazyLoadable)topic!; topic!.References.Deferred.Add(new("_stub", 11111)); - await ((ITopicLazyLoadable)topic).EnsureLoaded(TopicPayload.References); + await rawTopic.EnsureLoaded(TopicPayload.References); - Assert.True(((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.References)); + Assert.True(rawTopic.IsLoaded(TopicPayload.References)); } @@ -1282,11 +1286,12 @@ public async Task EnsureLoaded_ReferencesNotLoaded_MarksLoaded() { public async Task IsLoaded_ChildrenNotLoadedState_TriggersEnsureLoaded() { var topic = await _topicRepository.Load(11111); + var rawTopic = (ITopicLazyLoadable)topic!; - ((ITopicLazyLoadable)topic!).SetLoadState(TopicPayload.Children, LoadState.NotLoaded); + rawTopic.SetLoadState(TopicPayload.Children, LoadState.NotLoaded); _ = topic.Children; - Assert.True(((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.Children)); + Assert.True(rawTopic.IsLoaded(TopicPayload.Children)); } @@ -1302,11 +1307,12 @@ public async Task IsLoaded_ChildrenNotLoadedState_TriggersEnsureLoaded() { public async Task IsLoaded_ChildrenLoadedState_DoesNotCallResolver() { var topic = await _topicRepository.Load(11111); + var rawTopic = (ITopicLazyLoadable)topic!; - Assert.True(((ITopicLazyLoadable)topic!).IsLoaded(TopicPayload.Children)); + Assert.True(rawTopic.IsLoaded(TopicPayload.Children)); _ = topic.Children; - Assert.True(((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.Children)); + Assert.True(rawTopic.IsLoaded(TopicPayload.Children)); } @@ -1342,11 +1348,12 @@ public async Task IsLoaded_RelationshipsNotLoadedState_TriggersEnsureLoaded() { public async Task IsLoaded_RelationshipsLoadedState_DoesNotCallResolver() { var topic = await _topicRepository.Load(11111); + var rawTopic = (ITopicLazyLoadable)topic!; - Assert.True(((ITopicLazyLoadable)topic!).IsLoaded(TopicPayload.Relationships)); + Assert.True(rawTopic.IsLoaded(TopicPayload.Relationships)); _ = topic.Relationships; - Assert.True(((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.Relationships)); + Assert.True(rawTopic.IsLoaded(TopicPayload.Relationships)); } @@ -1382,11 +1389,12 @@ public async Task IsLoaded_ReferencesNotLoadedState_TriggersEnsureLoaded() { public async Task IsLoaded_ReferencesLoadedState_DoesNotCallResolver() { var topic = await _topicRepository.Load(11111); + var rawTopic = (ITopicLazyLoadable)topic!; - Assert.True(((ITopicLazyLoadable)topic!).IsLoaded(TopicPayload.References)); + Assert.True(rawTopic.IsLoaded(TopicPayload.References)); _ = topic.References; - Assert.True(((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.References)); + Assert.True(rawTopic.IsLoaded(TopicPayload.References)); } @@ -1402,11 +1410,12 @@ public async Task IsLoaded_ReferencesLoadedState_DoesNotCallResolver() { public async Task EnsureLoaded_ChildrenNotLoaded_MarksLoaded() { var topic = await _topicRepository.Load(11111); + var rawTopic = (ITopicLazyLoadable)topic!; - ((ITopicLazyLoadable)topic!).SetLoadState(TopicPayload.Children, LoadState.NotLoaded); - await ((ITopicLazyLoadable)topic).EnsureLoaded(TopicPayload.Children); + rawTopic.SetLoadState(TopicPayload.Children, LoadState.NotLoaded); + await rawTopic.EnsureLoaded(TopicPayload.Children); - Assert.True(((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.Children)); + Assert.True(rawTopic.IsLoaded(TopicPayload.Children)); } From a304e904001ae42f5a702e614d697159ad8dcd63 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 17 Jul 2026 20:36:39 -0700 Subject: [PATCH 205/337] Replace `ConnectResidentAssociations()` With `FindAll()` updated to return the entire topic graph, without a gate on `Children` `NotLoaded` (92a99954), the `GetTopicIndex()` method will now return a true, comprehensive topic index, thus fixing a number of bugs. This also allows us to get rid of `ConnectResidentAssociations()` in the `StubLazyLoadingTopicRepository`, which was relying on its own internal `_served` index, and instead rely on the new `ResolveAssociations()` method (167067f3) from the base `LazyLoadingTopicRepository`. This not only centralizes code, but also better maps onto what the live code is actually doing, thus providing a more representative test double. This contributes to the testing --- .../StubLazyLoadingTopicRepository.cs | 43 ++++--------------- 1 file changed, 9 insertions(+), 34 deletions(-) diff --git a/OnTopic.TestDoubles/LazyLoading/StubLazyLoadingTopicRepository.cs b/OnTopic.TestDoubles/LazyLoading/StubLazyLoadingTopicRepository.cs index b152936f..be812d63 100644 --- a/OnTopic.TestDoubles/LazyLoading/StubLazyLoadingTopicRepository.cs +++ b/OnTopic.TestDoubles/LazyLoading/StubLazyLoadingTopicRepository.cs @@ -322,10 +322,11 @@ await FillRequestedPayload( /// The topic whose requested payload should be filled. /// The requested flags. /// - /// Whether unresolved relationships and references targets should be recursively loaded, via the inherited - /// LoadDeferredAssociations. Set by 's on-demand - /// fill; left by a plain Load(), which only connects targets already present in the graph, - /// via . + /// Whether unresolved relationships and references targets should be recursively loaded, via the inherited . Set by 's on-demand fill; left by a plain + /// Load(), which only connects targets already present in the graph, via the inherited . /// /// /// Whether a requested boundary should recurse into the entire subtree, @@ -350,10 +351,12 @@ CancellationToken cancellationToken >------------------------------------------------------------------------------------------------------------------------- | Unconditionally connects targets already present in the graph, mirroring how LoadTopicGraph() reads relationship and | reference rows alongside every topic row and links whatever's already resident, regardless of the requested payload. - | Runs ahead of the payload/store checks below, since it isn't gated by them in production either. + | Runs ahead of the payload/store checks below, since it isn't gated by them in production either. Delegates to the + | inherited ResolveAssociations, which indexes the resident graph the same way LoadTopicGraph() seeds its working index + | (via GetTopicIndex()), so this double relies on the same underlying mechanism as production rather than a parallel one. \-------------------------------------------------------------------------------------------------------------------------*/ if (!resolveDeferredTargets) { - ConnectResidentAssociations(rawTopic); + await ResolveAssociations(topic, TopicPayload.Relationships | TopicPayload.References).ConfigureAwait(false); } /*-------------------------------------------------------------------------------------------------------------------------- @@ -463,34 +466,6 @@ CancellationToken cancellationToken } - /*============================================================================================================================ - | METHOD: CONNECT RESIDENT ASSOCIATIONS - \---------------------------------------------------------------------------------------------------------------------------*/ - /// - /// Connects each deferred relationship or reference entry whose target is already present in , without - /// recursively loading anything. Mirrors how a real, SQL-backed repository connects association targets found within the - /// same result set as the requested topic, leaving out-of-scope targets deferred for a later, explicit fill via . - /// - /// The requesting topic's backing accessor. - private void ConnectResidentAssociations(ITopicBackingAccessor rawTopic) { - - // Attempts to resolve each deferred relationship - foreach (var entry in rawTopic.Relationships.Deferred.ToArray()) { - if (_served.TryGetValue(entry.TopicId, out var target)) { - rawTopic.Relationships.SetValue(entry.Key, target, markDirty: false); - } - } - - // Attempts to resolve each deferred reference - foreach (var entry in rawTopic.References.Deferred.ToArray()) { - if (_served.TryGetValue(entry.TopicId, out var target)) { - rawTopic.References.SetValue(entry.Key, target, markDirty: false); - } - } - - } - /*============================================================================================================================ | METHOD: BUILD TOPIC WITH ANCESTORS \---------------------------------------------------------------------------------------------------------------------------*/ From ffdf518a8abd3e08a9ce249599bc1d60f79e3cc4 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 17 Jul 2026 21:01:02 -0700 Subject: [PATCH 206/337] Prefer `#region` over flowerboxes for grouping On other projects, we only use flowerboxes for grouping. For this project, however, we use them on every member. We may want to revisit that at some point. For now, however, we should prefer `#region` for grouping instead of flower boxes that get easily lost. This also gives us better visualization via IDEs with collapsable regions and even grouped members in the structure explorer. --- .../LazyLoadingTopicRepositoryTest.cs | 72 +++++++++---------- 1 file changed, 36 insertions(+), 36 deletions(-) diff --git a/OnTopic.Tests/LazyLoadingTopicRepositoryTest.cs b/OnTopic.Tests/LazyLoadingTopicRepositoryTest.cs index e260f4b3..fffa7d2d 100644 --- a/OnTopic.Tests/LazyLoadingTopicRepositoryTest.cs +++ b/OnTopic.Tests/LazyLoadingTopicRepositoryTest.cs @@ -69,9 +69,7 @@ public LazyLoadingTopicRepositoryTest() { _cachedTopicRepository = new(new StubLazyLoadingTopicRepository()); } - /*============================================================================================================================ - | A: GENUINE DEFERRAL ON LOAD - \---------------------------------------------------------------------------------------------------------------------------*/ + #region A: Genuine Deferral on Load /*============================================================================================================================ | TEST: LOAD: DEFAULT PAYLOAD: CHILDREN NOT LOADED @@ -128,9 +126,9 @@ public async Task Load_DefaultPayload_AssociationsDeferred() { } - /*============================================================================================================================ - | B: ON-DEMAND MATERIALIZATION VIA THE AUTOLOADING GETTERS - \---------------------------------------------------------------------------------------------------------------------------*/ + #endregion + + #region B: On-Demand Materialization via the Autoloading Getters /*============================================================================================================================ | TEST: CHILDREN: NOT LOADED: MATERIALIZES REAL CHILDREN @@ -186,9 +184,9 @@ public async Task References_NotLoaded_MaterializesTargets() { } - /*============================================================================================================================ - | C: ON-DEMAND MATERIALIZATION VIA ASYNC ENSURE LOADED - \---------------------------------------------------------------------------------------------------------------------------*/ + #endregion + + #region C: On-Demand Materialization via Async Ensure Loaded /*============================================================================================================================ | TEST: ENSURE LOADED: CHILDREN: MATERIALIZES BEFORE ACCESS @@ -233,9 +231,9 @@ public async Task EnsureLoaded_ExtendedAttributes_MaterializesRealValue() { } - /*============================================================================================================================ - | D: FETCH-ONCE (SPY) - \---------------------------------------------------------------------------------------------------------------------------*/ + #endregion + + #region D: Fetch-Once (Spy) /*============================================================================================================================ | TEST: CHILDREN: ACCESSED TWICE: FETCHES ONCE @@ -276,9 +274,9 @@ public async Task EnsureLoaded_AlreadyLoaded_DoesNotFetch() { } - /*============================================================================================================================ - | E: RECURSIVE LAZY DESCENT - \---------------------------------------------------------------------------------------------------------------------------*/ + #endregion + + #region E: Recursive Lazy Descent /*============================================================================================================================ | TEST: CHILDREN: MATERIALIZED CHILD: IS ITSELF LAZY @@ -304,9 +302,9 @@ public async Task Children_MaterializedChild_IsItselfLazy() { } - /*============================================================================================================================ - | F: RESOLVER STAMPING THROUGH THE PUBLIC PATH - \---------------------------------------------------------------------------------------------------------------------------*/ + #endregion + + #region F: Resolver Stamping through the Public Path /*============================================================================================================================ | TEST: LOAD: SERVED NODE: IS STAMPED @@ -411,9 +409,9 @@ public async Task Save_NewTopic_StampsResolver() { } - /*============================================================================================================================ - | G: FORCE-LOAD GATE (STAMPING MUST NOT FILL) - \---------------------------------------------------------------------------------------------------------------------------*/ + #endregion + + #region G: Force-Load Gate (Stamping Must Not Fill) /*============================================================================================================================ | TEST: CHILDREN: MATERIALIZED: STAMPING DOES NOT LOAD GRANDCHILDREN @@ -439,9 +437,9 @@ public async Task Children_Materialized_StampingDoesNotLoadGrandchildren() { } - /*============================================================================================================================ - | H: DEFERRED-ASSOCIATION RESOLUTION THROUGH THE CACHE DECORATOR - \---------------------------------------------------------------------------------------------------------------------------*/ + #endregion + + #region H: Deferred-Association Resolution through the Cache Decorator /*============================================================================================================================ | TEST: ENSURE LOADED: STALE RELATIONSHIP TARGET: IS DISCARDED @@ -506,9 +504,9 @@ public async Task EnsureLoaded_MissingReferenceTarget_ResolvesAndConnects() { } - /*============================================================================================================================ - | I: DECORATOR STAMP PRECEDENCE - \---------------------------------------------------------------------------------------------------------------------------*/ + #endregion + + #region I: Decorator Stamp Precedence /*============================================================================================================================ | TEST: LOAD: DECORATED: OUTER RESOLVER WINS @@ -527,9 +525,9 @@ public async Task Load_Decorated_OuterResolverWins() { } - /*============================================================================================================================ - | J: EDGE CASES - \---------------------------------------------------------------------------------------------------------------------------*/ + #endregion + + #region J: Edge Cases /*============================================================================================================================ | TEST: ENSURE LOADED: NEW TOPIC: DOES NOT FETCH @@ -550,9 +548,9 @@ public async Task EnsureLoaded_NewTopic_DoesNotFetch() { } - /*============================================================================================================================ - | K: IN-GRAPH ASSOCIATION RESOLUTION - \---------------------------------------------------------------------------------------------------------------------------*/ + #endregion + + #region K: In-Graph Association Resolution /*============================================================================================================================ | TEST: ENSURE LOADED: TARGETS RESIDENT IN GRAPH: RESOLVE AND CLEAR DEFERRED @@ -587,9 +585,9 @@ public async Task EnsureLoaded_TargetsResidentInGraph_ResolveAndClearDeferred() } - /*============================================================================================================================ - | L: SUFFICIENCY-GATED CACHE HITS - \---------------------------------------------------------------------------------------------------------------------------*/ + #endregion + + #region L: Sufficiency-Gated Cache Hits /*============================================================================================================================ | TEST: LOAD: NARROW PAYLOAD HIT: TOPS UP AND CONVERGES @@ -758,4 +756,6 @@ public async Task Load_WholeTreeTopUp_MaterializesThenCleanHit() { } + #endregion + } //Class \ No newline at end of file From aecee854eca850422e932e791edeb8eeab98b167 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sun, 19 Jul 2026 02:33:32 -0700 Subject: [PATCH 207/337] Introduce `autoLoad` overload to `GetValue()` The new `autoLoad` parameter to the `AttributeCollection.GetValue()` (and its underlying `TrackedRecordCollection<>.GetValue()`) allows a request for an attribute to skip the lazy loading of extended attributes if it's assumed that the attribute is indexed. Positively, this allows us to by pass an on-demand, potentially recursive load of extended attributes up e.g., the parent and/or base chain. Negatively, a false positive results in the extended attributes not being loaded for a specific attribute that may have been configured to be extended, despite normally being indexed (e.g., `IsHidden`). This provides an important, if mildly risky bypass of the lazy-loading infrastructure (#111). --- OnTopic/Attributes/AttributeCollection.cs | 27 ++++++++++++++----- ...cordCollection{TItem,TValue,TAttribute}.cs | 17 +++++++++--- 2 files changed, 35 insertions(+), 9 deletions(-) diff --git a/OnTopic/Attributes/AttributeCollection.cs b/OnTopic/Attributes/AttributeCollection.cs index 0db0848b..dc51f217 100644 --- a/OnTopic/Attributes/AttributeCollection.cs +++ b/OnTopic/Attributes/AttributeCollection.cs @@ -5,6 +5,7 @@ \=============================================================================================================================*/ using OnTopic.Collections.Specialized; +using OnTopic.Metadata; using OnTopic.Repositories; namespace OnTopic.Attributes; @@ -102,13 +103,17 @@ public bool IsDirty(bool excludeLastModified) | METHOD: GET VALUE \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Retrieves the value associated with the specified , autoloading the extended-attribute blob if the - /// key is not yet loaded and the extended-attribute boundary is . + /// Retrieves the value associated with the specified , autoloading the extended attribute blob if the + /// key is not yet loaded and the extended attribute property is set to . /// /// /// Indexed attributes are always loaded in the local collection; the autoload is skipped for them. A deferred key that has /// never been fetched triggers a single synchronous blob fill through the stamped resolver; all subsequent reads find the - /// boundary and return immediately without an additional round-trip. + /// property and return immediately without an additional round-trip. Callers that know a key + /// is always indexed and, thus, never resides in the extended attribute blob, may set to + /// false to suppress this behavior. This is a correctness trade-off: An can force + /// any attribute to be treated as extended, in which case a value stored only in an unloaded blob will be missed and the + /// returned instead. It should therefore only be used for attributes known to be indexed. /// /// The string identifier for the . /// A string value to which to fall back in the case the value is not found. @@ -116,12 +121,22 @@ public bool IsDirty(bool excludeLastModified) /// Determines if the value should be inherited from the parent topic when not found locally. /// /// The maximum number of ancestor hops when inheriting from parent topics. + /// + /// Determines whether a extended attribute property may trigger a synchronous load when + /// is absent locally. Defaults to true. + /// [return: NotNullIfNotNull(nameof(defaultValue))] - internal override string? GetValue(string key, string? defaultValue, bool inheritFromParent, int maxHops) { - if (LoadState is LoadState.NotLoaded && !Contains(key)) { + internal override string? GetValue( + string key, + string? defaultValue, + bool inheritFromParent, + int maxHops, + bool autoLoad = true + ) { + if (autoLoad && LoadState is LoadState.NotLoaded && !Contains(key)) { ((ITopicLazyLoadable)AssociatedTopic).EnsureLoaded(TopicPayload.ExtendedAttributes); } - return base.GetValue(key, defaultValue, inheritFromParent, maxHops); + return base.GetValue(key, defaultValue, inheritFromParent, maxHops, autoLoad); } /*============================================================================================================================ diff --git a/OnTopic/Collections/Specialized/TrackedRecordCollection{TItem,TValue,TAttribute}.cs b/OnTopic/Collections/Specialized/TrackedRecordCollection{TItem,TValue,TAttribute}.cs index 321f723c..d37dd006 100644 --- a/OnTopic/Collections/Specialized/TrackedRecordCollection{TItem,TValue,TAttribute}.cs +++ b/OnTopic/Collections/Specialized/TrackedRecordCollection{TItem,TValue,TAttribute}.cs @@ -223,6 +223,10 @@ public void MarkClean(string key, DateTime? version) { /// Boolean indicator nothing whether to recusrively search through s in order to get the value. /// /// The number of recursions to perform when attempting to get the value. + /// + /// Indicates whether a deferred-loading subclass may trigger a load when the key is absent locally. Defaults to + /// true. + /// /// The value for the . /// /// !String.IsNullOrWhiteSpace(key) @@ -241,7 +245,13 @@ public void MarkClean(string key, DateTime? version) { /// maxHops <= 100 /// [return: NotNullIfNotNull(nameof(defaultValue))] - internal virtual TValue? GetValue(string key, TValue? defaultValue, bool inheritFromParent, int maxHops) { + internal virtual TValue? GetValue( + string key, + TValue? defaultValue, + bool inheritFromParent, + int maxHops, + bool autoLoad = true + ) { /*-------------------------------------------------------------------------------------------------------------------------- | Validate contracts @@ -271,7 +281,7 @@ value is null && maxHops > 0 && BaseCollection is not null ) { - value = BaseCollection.GetValue(key, null, false, maxHops - 1); + value = BaseCollection.GetValue(key, null, false, maxHops - 1, autoLoad); } /*-------------------------------------------------------------------------------------------------------------------------- @@ -282,7 +292,8 @@ value is null && inheritFromParent && ParentCollection is not null ) { - value = ParentCollection.GetValue(key, defaultValue, inheritFromParent); + // Literal 5 preserves the base-inheritance restart applied by the public overload + value = ParentCollection.GetValue(key, defaultValue, inheritFromParent, 5, autoLoad); } /*-------------------------------------------------------------------------------------------------------------------------- From 42495b9d01352e5a7793c2174b2bba3adc84f5f1 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sun, 19 Jul 2026 02:42:59 -0700 Subject: [PATCH 208/337] Presume bool, date, number attributes are indexed The expectation is that `Boolean`, `DateTime`, `Integer`, `Double`, and generally `Uri` data types will be indexed, due to their short length and, often, common need for e.g., filtering topics. As such, we prevent `GetBoolean()`, `GetInteger()`, `GetDouble()`, `GetDateTime()`, and `GetUri()` to disable the new `autoLoad` parameter on `Topic.Attributes.GetValue()` (aecee854). The result is that attributes called via these extension methods will never trigger a lazy-load. _This could result in false negatives._ (If e.g., a boolean is stored as an extended attribute, or if a URI is longer than 255 characters.) That said, any request outside of these, as expected on a page load, will retrieve the extended attributes entirely, and resolve any potential misses here. The goal is to address the main cases. This also picks up the calls to `Title` and `View`, which don't use any of the `AttributeCollectionExtensions`, but similarly fall into the expectations of indexed. This provides an important, if mildly risky bypass of the lazy-loading infrastructure (#111). --- .../Attributes/AttributeCollectionExtensions.cs | 17 +++++++++++------ OnTopic/Topic.cs | 4 ++-- 2 files changed, 13 insertions(+), 8 deletions(-) diff --git a/OnTopic/Attributes/AttributeCollectionExtensions.cs b/OnTopic/Attributes/AttributeCollectionExtensions.cs index b0343358..02160055 100644 --- a/OnTopic/Attributes/AttributeCollectionExtensions.cs +++ b/OnTopic/Attributes/AttributeCollectionExtensions.cs @@ -48,9 +48,10 @@ public static bool GetBoolean( return AttributeValueConverter.Convert( attributes.GetValue( name, - defaultValue ? "1" : "0", + defaultValue ? "1" : "0", inheritFromParent, - inheritFromBase ? 5 : 0 + inheritFromBase ? 5 : 0, + autoLoad : false ) )?? defaultValue; } @@ -87,7 +88,8 @@ public static int GetInteger( name, defaultValue.ToString(CultureInfo.InvariantCulture), inheritFromParent, - inheritFromBase? 5 : 0 + inheritFromBase ? 5 : 0, + autoLoad : false ) )?? defaultValue; } @@ -124,7 +126,8 @@ public static double GetDouble( name, defaultValue.ToString(CultureInfo.InvariantCulture), inheritFromParent, - inheritFromBase? 5 : 0 + inheritFromBase ? 5 : 0, + autoLoad : false ) )?? defaultValue; } @@ -161,7 +164,8 @@ public static DateTime GetDateTime( name, defaultValue.ToString(CultureInfo.InvariantCulture), inheritFromParent, - inheritFromBase ? 5 : 0 + inheritFromBase ? 5 : 0, + autoLoad : false ) )?? defaultValue; } @@ -198,7 +202,8 @@ public static DateTime GetDateTime( name, null, inheritFromParent, - inheritFromBase ? 5 : 0 + inheritFromBase ? 5 : 0, + autoLoad : false ) )?? defaultValue; } diff --git a/OnTopic/Topic.cs b/OnTopic/Topic.cs index 870f05f2..8d4a9a4b 100644 --- a/OnTopic/Topic.cs +++ b/OnTopic/Topic.cs @@ -293,7 +293,7 @@ internal string? OriginalKey { [AttributeSetter] public string? View { get => - Attributes.GetValue("View", ""); + Attributes.GetValue("View", "", false, 5, autoLoad: false); set { TopicFactory.ValidateKey(value, true); SetAttributeValue("View", value); @@ -382,7 +382,7 @@ public bool IsDisabled { /// !string.IsNullOrWhiteSpace(value) /// public string Title { - get => Attributes.GetValue("Title", Key); + get => Attributes.GetValue("Title", Key, false, 5, autoLoad: false); set => SetAttributeValue("Title", value); } From f94932d10c736cecc6a56813a91534cb7d88ca8c Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sun, 19 Jul 2026 02:50:49 -0700 Subject: [PATCH 209/337] Introduced unit tests for index auto-load bypass This provides tests for `AttributeCollection.GetValue()` to confirm when it does and doesn't trigger `autoLoad` (42495b9d, 42495b9d). This ensures that the (presumably) indexed attributes bypass lazy-lazy loading, and vice versa. This contributes to the testing of the lazy-loading infrastructure (#111). --- OnTopic.Tests/AttributeCollectionTest.cs | 83 ++++++++++++++++++++++++ OnTopic.Tests/TopicTest.cs | 46 +++++++++++++ 2 files changed, 129 insertions(+) diff --git a/OnTopic.Tests/AttributeCollectionTest.cs b/OnTopic.Tests/AttributeCollectionTest.cs index f966441b..1a9ddaa4 100644 --- a/OnTopic.Tests/AttributeCollectionTest.cs +++ b/OnTopic.Tests/AttributeCollectionTest.cs @@ -6,7 +6,9 @@ using System.Collections; using System.Globalization; using OnTopic.Collections.Specialized; +using OnTopic.Repositories; using OnTopic.Tests.Entities; +using OnTopic.Tests.TestDoubles; using Xunit; namespace OnTopic.Tests; @@ -92,6 +94,55 @@ public void GetValue_EmptyValue_ReturnsNull() { } + + /*============================================================================================================================ + | TEST: GET VALUE: NOT LOADED: KEY ABSENT: TRIGGERS LOAD + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Creates a topic stamped with a and a that is + /// . Confirms that a raw call, which defaults autoLoad to + /// true, still triggers a lazy load for a key that isn't present locally. This guards against over-suppression of + /// the autoload behavior. + /// + [Fact] + public void GetValue_NotLoaded_KeyAbsent_TriggersLoad() { + + var topic = new Topic("Test", "Container"); + var loader = new TrackingTopicLazyLoader(); + + ((ITopicLazyLoadable)topic).Loader = loader; + topic.Attributes.LoadState = LoadState.NotLoaded; + + topic.Attributes.GetValue("Missing"); + + Assert.True(loader.WasCalled); + + } + + /*============================================================================================================================ + | TEST: GET VALUE: LOADED: KEY ABSENT: DOES NOT TRIGGER LOAD + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Creates a topic stamped with a whose is already + /// . Confirms that requesting an absent key never triggers a lazy load, preserving existing + /// behavior on fully loaded collections. + /// + [Fact] + public void GetValue_Loaded_KeyAbsent_DoesNotTriggerLoad() { + + var topic = new Topic("Test", "Container"); + var loader = new TrackingTopicLazyLoader(); + + ((ITopicLazyLoadable)topic).Loader = loader; + + topic.Attributes.GetValue("Missing"); + + Assert.False(loader.WasCalled); + + } + + /*============================================================================================================================ | TEST: GET INTEGER: CORRECT VALUE: IS RETURNED \---------------------------------------------------------------------------------------------------------------------------*/ @@ -404,6 +455,38 @@ public void GetBoolean_IncorrectKey_ReturnDefault() { } + /*============================================================================================================================ +| TEST: GET BOOLEAN: NOT LOADED: KEY ABSENT: SUPPRESSES AUTO LOAD +\---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Creates a topic and a , both stamped with a and both + /// with a . Confirms that —used only for + /// always-indexed attributes—suppresses the autoload on both the topic and its base topic. + /// + [Fact] + public void GetBoolean_NotLoaded_KeyAbsent_SuppressesAutoLoad() { + + var baseTopic = new Topic("Base", "Container"); + var topic = new Topic("Test", "Container"); + var loader = new TrackingTopicLazyLoader(); + var baseLoader = new TrackingTopicLazyLoader(); + + topic.BaseTopic = baseTopic; + + ((ITopicLazyLoadable)topic).Loader = loader; + ((ITopicLazyLoadable)baseTopic).Loader = baseLoader; + + topic.Attributes.LoadState = LoadState.NotLoaded; + baseTopic.Attributes.LoadState = LoadState.NotLoaded; + + topic.Attributes.GetBoolean("Missing"); + + Assert.False(loader.WasCalled); + Assert.False(baseLoader.WasCalled); + + } + /*============================================================================================================================ | TEST: GET URI: INHERITED VALUE: IS RETURNED \---------------------------------------------------------------------------------------------------------------------------*/ diff --git a/OnTopic.Tests/TopicTest.cs b/OnTopic.Tests/TopicTest.cs index 53ad8f3e..f0598d26 100644 --- a/OnTopic.Tests/TopicTest.cs +++ b/OnTopic.Tests/TopicTest.cs @@ -5,6 +5,8 @@ \=============================================================================================================================*/ using OnTopic.Collections; using OnTopic.Metadata; +using OnTopic.Repositories; +using OnTopic.Tests.TestDoubles; using Xunit; namespace OnTopic.Tests; @@ -255,6 +257,50 @@ public void Title_NullValue_ReturnsKey() { } + /*============================================================================================================================ + | TEST: TITLE: NOT LOADED: KEY ABSENT: DOES NOT TRIGGER LOAD + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Creates a topic stamped with a and a collection. Confirms that falls back to without + /// triggering a lazy load, since Title is always expected to be indexed. + /// + [Fact] + public void Title_NotLoaded_KeyAbsent_DoesNotTriggerLoad() { + + var topic = new Topic("Test", "Page"); + var loader = new TrackingTopicLazyLoader(); + + ((ITopicLazyLoadable)topic).Loader = loader; + topic.Attributes.LoadState = LoadState.NotLoaded; + + Assert.Equal("Test", topic.Title); + Assert.False(loader.WasCalled); + + } + + /*============================================================================================================================ + | TEST: VIEW: NOT LOADED: KEY ABSENT: DOES NOT TRIGGER LOAD + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Creates a topic stamped with a and a collection. Confirms that falls back to without + /// triggering a lazy load, since View is always expected to be indexed. + /// + [Fact] + public void View_NotLoaded_KeyAbsent_DoesNotTriggerLoad() { + + var topic = new Topic("Test", "Page"); + var loader = new TrackingTopicLazyLoader(); + + ((ITopicLazyLoadable)topic).Loader = loader; + topic.Attributes.LoadState = LoadState.NotLoaded; + + Assert.Equal("", topic.View); + Assert.False(loader.WasCalled); + + } + /*============================================================================================================================ | TEST: LAST MODIFIED: UPDATE VALUE: RETURNS EXPECTED VALUE \---------------------------------------------------------------------------------------------------------------------------*/ From 74b5e4262b72d143ee0702acae2d1907cda8e589 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sun, 19 Jul 2026 02:57:02 -0700 Subject: [PATCH 210/337] Ensure `cancellationToken` is documented correctly For some reason, when I initially migrated `ITopicRepository` to be `async` (a3b73602, caab55a2), I missed setting the XML docblocks for the new `cancellationToken` parameter. Also picked up some additional missing parameters on `ITopicLazyLoader.EnsureLoaded()`, as related to the lazy-loading dependency (#111). Whoops! --- OnTopic.Data.Sql/SqlDataReaderExtensions.cs | 2 ++ OnTopic/Repositories/ITopicLazyLoader.cs | 5 +++++ 2 files changed, 7 insertions(+) diff --git a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs index da36b17d..2d95851c 100644 --- a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs +++ b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs @@ -57,6 +57,7 @@ internal static class SqlDataReaderExtensions { /// cref="Topic.BaseTopic"/>. This is useful for cases where it's known that a shallow copy is being retrieved, and /// thus external references aren't likely to be available. /// + /// An optional token that can be used to cancel the operation. /*============================================================================================================================ | METHOD: LOAD TOPIC GRAPH \---------------------------------------------------------------------------------------------------------------------------*/ @@ -277,6 +278,7 @@ private static Topic AddTopic(this IDataReader reader, TopicIndex topics, bool? /// /// The topic whose immediate children are being loaded. /// The to populate with the new child topics. + /// An optional token that can be used to cancel the operation. internal static async Task FillChildren( this DbDataReader reader, Topic parent, diff --git a/OnTopic/Repositories/ITopicLazyLoader.cs b/OnTopic/Repositories/ITopicLazyLoader.cs index 41774f9a..03ab8a60 100644 --- a/OnTopic/Repositories/ITopicLazyLoader.cs +++ b/OnTopic/Repositories/ITopicLazyLoader.cs @@ -24,6 +24,11 @@ public interface ITopicLazyLoader { /// fetching and merging whichever of them are not yet and silently skipping those already /// loaded. Invoked by the autoloading property getters, each with its own flag. /// + /// The whose payload should be ensured to be loaded. + /// + /// One or more flags identifying the payload that should be ensured to be loaded. + /// + /// An optional token that can be used to cancel the operation. Task EnsureLoaded(Topic topic, TopicPayload payload, CancellationToken cancellationToken = default); } //Interface \ No newline at end of file From a54bebddc14ada44dde93d9dabd2273a44f78cc4 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sun, 19 Jul 2026 20:17:58 -0700 Subject: [PATCH 211/337] Fallback to cache if `referenceTopic` is null When I added the fallback to the underlying `TopicRepository.Load()` from the `CachedTopicRepository.Load()` (599c5bef), I correctly relayed the `referenceTopic`, if present, but neglected to pass the local cache if it wasn't. In that case, the topic would be loaded, but wouldn't be integrated into the existing cache, in a way that `MergeIntoCache()` still expects. This contributes to #111. --- OnTopic.Data.Caching/CachedTopicRepository.cs | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/OnTopic.Data.Caching/CachedTopicRepository.cs b/OnTopic.Data.Caching/CachedTopicRepository.cs index 960ee247..b997e15d 100644 --- a/OnTopic.Data.Caching/CachedTopicRepository.cs +++ b/OnTopic.Data.Caching/CachedTopicRepository.cs @@ -89,8 +89,9 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos /// Returns a cached topic if it satisfies the requested and ; an /// insufficient hit is topped up via before being returned. On a /// miss, falls through to the underlying repository with @LoadAscendants enabled so the full ancestor chain is - /// fetched and merged into the live graph. Missing IDs are recorded to prevent redundant round-trips for topics that - /// genuinely do not exist. + /// fetched and merged into the live graph, using if supplied, or the cache root + /// otherwise, so the underlying load seeds its working index from, and can attach directly to, the resident graph. Missing + /// IDs are recorded to prevent redundant round-trips for topics that do not exist. /// public override async Task Load( int topicId, @@ -132,7 +133,7 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos | On miss: Load with ancestors and merge result into the live graph \-------------------------------------------------------------------------------------------------------------------------*/ var loaded = await TopicRepository - .Load(topicId, referenceTopic, isRecursive, payload) + .Load(topicId, referenceTopic?? _cache, isRecursive, payload) .ConfigureAwait(false); // If it's missing, populate the appropriate index so we don't try loading it again @@ -159,8 +160,9 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos /// Returns a cached topic if it satisfies the requested and ; an /// insufficient hit is topped up via before being returned. On a /// miss, falls through to the underlying repository with @LoadAscendants enabled so the full ancestor chain is - /// fetched and merged into the live graph. Missing IDs are recorded to prevent redundant round-trips for topics that - /// genuinely do not exist. + /// fetched and merged into the live graph, using if supplied, or the cache root + /// otherwise, so the underlying load seeds its working index from, and can attach directly to, the resident graph. Missing + /// IDs are recorded to prevent redundant round-trips for topics that do not exist. /// public override async Task Load( string uniqueKey, @@ -211,7 +213,7 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos | On miss: Load with ancestors and merge result into the live graph \-------------------------------------------------------------------------------------------------------------------------*/ var loaded = await TopicRepository - .Load(uniqueKey, referenceTopic, isRecursive, payload) + .Load(uniqueKey, referenceTopic?? _cache, isRecursive, payload) .ConfigureAwait(false); if (loaded is null) { From de1784eae13bb9e39c7fa4264190dc9e5ba39e5a Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sun, 19 Jul 2026 21:16:03 -0700 Subject: [PATCH 212/337] Introduced new `FakeSqlTopicRepository` This provides a new test double mimicking the `SqlTopicRepository`, specifically, in that it a) utilizes the `LoadTopicGraph()` under the hood, and b) always returns new instances, independent of what's already been loaded or cached, as the existing `StubTopicRepository` and `StubLazyLoadingTopicRepository` do. This will contribute to the testing of the lazy-loading merge capabilities (#111) when dealing with different instances of the same topic. --- .../TestDoubles/FakeSqlTopicRepository.cs | 194 ++++++++++++++++++ 1 file changed, 194 insertions(+) create mode 100644 OnTopic.Tests/TestDoubles/FakeSqlTopicRepository.cs diff --git a/OnTopic.Tests/TestDoubles/FakeSqlTopicRepository.cs b/OnTopic.Tests/TestDoubles/FakeSqlTopicRepository.cs new file mode 100644 index 00000000..1b55914d --- /dev/null +++ b/OnTopic.Tests/TestDoubles/FakeSqlTopicRepository.cs @@ -0,0 +1,194 @@ +/*============================================================================================================================== +| Author Ignia, LLC +| Client Ignia, LLC +| Project Topics Library +\=============================================================================================================================*/ +using System.Data; +using OnTopic.Data.Sql; +using OnTopic.Repositories; +using OnTopic.TestDoubles.LazyLoading; +using OnTopic.Tests.Schemas; + +namespace OnTopic.Tests.TestDoubles; + +/*============================================================================================================================== +| CLASS: FAKE SQL TOPIC REPOSITORY +\-----------------------------------------------------------------------------------------------------------------------------*/ +/// +/// A fake for that serves an in-memory row set through the real, production , exactly as feeds it from a live SQL data +/// reader. Every request loads the full ascendant chain from the requested topic to the root, matching production's +/// @LoadAscendants = (topicId >= 0) behavior. +/// +/// +/// Unlike and stubs that +/// each maintain a single, persistent, already materialized graph and simply return existing instances +/// from it, this is a fake: It rebuilds a fresh subgraph from its row store on every call, via the same +/// entry point uses, and relies on the +/// caller's referenceTopic to reconcile new rows against an already resident graph, exactly as production does. That +/// is the specific mechanism under test in 's referenceTopic ?? _cache +/// regression tests: Neither of the other two doubles can distinguish a referenceTopic from a +/// resident one, since neither ever produces a duplicate instance to reconcile in the first place. +/// +[ExcludeFromCodeCoverage] +internal sealed class FakeSqlTopicRepository : TopicRepository { + + /*============================================================================================================================ + | VARIABLES + \---------------------------------------------------------------------------------------------------------------------------*/ + private readonly Dictionary _rows = []; + private readonly List<(int SourceId, string Key, int TargetId)> _relationships = []; + private readonly Dictionary _keyIndex = new(StringComparer.OrdinalIgnoreCase); + private int _identity = 90000; + + /*============================================================================================================================ + | METHOD: ADD TOPIC + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Registers a row in the fake row store, keyed by , and indexes its unique key for lookups. + /// + public FakeSqlTopicRepository AddTopic(int id, string key, string contentType, int? parentId) { + _rows[id] = (key, contentType, parentId); + _keyIndex[GetUniqueKey(id)] = id; + return this; + } + + /*============================================================================================================================ + | METHOD: ADD RELATIONSHIP + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Registers a relationship row, returned alongside its source topic's ascendant chain on a subsequent . + /// + public void AddRelationship(int sourceId, string key, int targetId) => _relationships.Add((sourceId, key, targetId)); + + /*============================================================================================================================ + | METHOD: GET UNIQUE KEY + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Computes the unique key for by walking its ParentId chain through the row store. + /// + private string GetUniqueKey(int id) { + List segments = []; + var current = (int?)id; + while (current is { } currentId) { + segments.Insert(0, _rows[currentId].Key); + current = _rows[currentId].ParentId; + } + return String.Join(":", segments); + } + + /*============================================================================================================================ + | METHOD: LOAD + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + public override async Task Load( + string uniqueKey, + Topic? referenceTopic = null, + bool isRecursive = false, + TopicPayload payload = TopicPayload.None + ) { + if (!_keyIndex.TryGetValue(uniqueKey, out var topicId)) { + return null; + } + return await Load(topicId, referenceTopic, isRecursive, payload).ConfigureAwait(false); + } + + /// + /// + /// Builds the requested topic's ascendant chain into fresh / rows on every call, then feeds them through the real —reproducing + /// the new instance per call, reconciled against the referenceTopic behavior of . + /// + public override async Task Load( + int topicId, + Topic? referenceTopic = null, + bool isRecursive = false, + TopicPayload payload = TopicPayload.None + ) { + + // Bypass for rowstore misses + if (!_rows.ContainsKey(topicId)) { + return null; + } + + // Build the ascendant chain, root-first, mirroring production's @LoadAscendants = (topicId >= 0) + List chain = []; + var current = (int?)topicId; + while (current is { } id) { + chain.Insert(0, id); + current = _rows[id].ParentId; + } + + // Define source data tables + using var topics = new TopicsDataTable(); + using var attributes = new AttributesDataTable(); + using var extendedAttributes = new AttributesDataTable(); + using var relationships = new RelationshipsDataTable(); + + // Build the descendant data + foreach (var id in chain) { + var (key, contentType, parentId) = _rows[id]; + var hasChildren = _rows.Values.Any(row => row.ParentId == id); + topics.AddRow(id, key, contentType, parentId, hasChildren: hasChildren); + } + + // Build the relationship data + foreach (var (sourceId, key, targetId) in _relationships.Where(r => chain.Contains(r.SourceId))) { + relationships.AddRow(sourceId, key, targetId, isDeleted: false); + } + + // Establish data table reader, which simulates the return from the GetTopics stored procedure + using var tableReader = new DataTableReader([topics, attributes, extendedAttributes, relationships]); + + // Delegate to the standard LoadTopicGraph from the SQL provider + var topic = await tableReader.LoadTopicGraph( + topicId, + referenceTopic, + cancellationToken : CancellationToken.None + ).ConfigureAwait(false); + + // Raise the TopicLoaded event + OnTopicLoaded(new(topic!, isRecursive)); + + // Finally, return the seed topic + return topic; + + } + + /// + public override async Task Load(int topicId, DateTime version, Topic? referenceTopic = null) => + await Load(topicId, referenceTopic).ConfigureAwait(false); + + /*============================================================================================================================ + | METHOD: REFRESH + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + public override Task Refresh(Topic referenceTopic, DateTime since) => Task.CompletedTask; + + /*============================================================================================================================ + | METHOD: SAVE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + protected override Task SaveTopic(Topic topic, DateTime version, bool persistRelationships) { + if (topic.IsNew) { + topic.Id = _identity++; + } + return Task.CompletedTask; + } + + /*============================================================================================================================ + | METHOD: MOVE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + protected override Task MoveTopic(Topic topic, Topic target, Topic? sibling = null) => Task.CompletedTask; + + /*============================================================================================================================ + | METHOD: DELETE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + protected override Task DeleteTopic(Topic topic) => Task.CompletedTask; + +} //Class \ No newline at end of file From 14eae8008225c28f0ecc5d392d688cf28fb90d48 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Mon, 20 Jul 2026 01:19:40 -0700 Subject: [PATCH 213/337] Implemented unit tests w/ `FakeSqlTopicRepository` This takes advantage of the newly introduced `FakeSqlTopicRepository` (de1784ea) as a backing service for the `CachedTopicRepository` so that it can evaluate the new (as of this branch) implementation of the underlying `TopicRepository` fallback (599c5bef). This contributes to the testing of #111. --- OnTopic.Tests/CachedTopicRepositoryTest.cs | 180 +++++++++++++++++++++ 1 file changed, 180 insertions(+) create mode 100644 OnTopic.Tests/CachedTopicRepositoryTest.cs diff --git a/OnTopic.Tests/CachedTopicRepositoryTest.cs b/OnTopic.Tests/CachedTopicRepositoryTest.cs new file mode 100644 index 00000000..d9cf1cc2 --- /dev/null +++ b/OnTopic.Tests/CachedTopicRepositoryTest.cs @@ -0,0 +1,180 @@ +/*============================================================================================================================== +| Author Ignia, LLC +| Client Ignia, LLC +| Project Topics Library +\=============================================================================================================================*/ +using System.Data; +using OnTopic.Data.Caching; +using OnTopic.Data.Sql; +using OnTopic.Querying; +using OnTopic.Repositories; +using OnTopic.TestDoubles.LazyLoading; +using OnTopic.Tests.TestDoubles; +using Xunit; + +namespace OnTopic.Tests; + +/*============================================================================================================================== +| CLASS: CACHED TOPIC REPOSITORY TESTS +\-----------------------------------------------------------------------------------------------------------------------------*/ +/// +/// Provides unit tests for the class. +/// +/// +/// These tests drive a , which is a minimal inner that +/// calls the real, production against in-memory +/// rows, exactly as does against a live SQL data reader, rather than , which deliberately ignores referenceTopic, and thus cannot distinguish a referenceTopic from _cache: The very two defects the referenceTopic ?? _cache +/// fallback resolves are intrinsic to 's referenceTopic-seeded +/// working index, which only exercises. +/// +[ExcludeFromCodeCoverage] +public class CachedTopicRepositoryTest { + + /*============================================================================================================================ + | PROPERTY: CANCELLATION TOKEN + \---------------------------------------------------------------------------------------------------------------------------*/ + private static CancellationToken CancellationToken => TestContext.Current.CancellationToken; + + /*============================================================================================================================ + | TEST: LOAD: COLD MISS WITH RESIDENT PARENT: ATTACHES TO RESIDENT INSTANCE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Loads a topic ("Web") non-recursively, leaving , then + /// loads a direct child ("Web_0") by ID, confirming the child attaches to the existing "Web" instance, populated via its + /// , with a matching , rather than dangling off a disconnected + /// duplicate. + /// + [Fact] + public async Task Load_ColdMissWithResidentParent_AttachesToResidentInstance() { + + var inner = new FakeSqlTopicRepository() + .AddTopic(1, "Root", "Container", null) + .AddTopic(2, "Web", "Page", 1) + .AddTopic(3, "Web_0", "Page", 2); + + var cache = new CachedTopicRepository(inner); + var root = await cache.Load("Root"); + var web = await cache.Load("Web"); + + Assert.False(((ITopicLazyLoadable)web!).IsLoaded(TopicPayload.Children)); + + var web0 = await cache.Load(3); + + Assert.NotNull(web0); + Assert.Same(web, web0.Parent); + Assert.Contains(web!.Children, child => child.Id == web0.Id); + Assert.Same(root, web0.GetRootTopic()); + + } + + /*============================================================================================================================ + | TEST: LOAD: COLD MISS TWO LEVELS BELOW RESIDENT ANCESTOR: ATTACHES WHOLE CHAIN + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Cold-loads a topic ("Web_0_0") two levels below the deepest resident ancestor ("Web") and confirms the entire new + /// intermediate chain ("Web_0") attaches under the resident ancestor rather than duplicating it. + /// + [Fact] + public async Task Load_ColdMissTwoLevelsBelowResidentAncestor_AttachesWholeChain() { + + var inner = new FakeSqlTopicRepository() + .AddTopic(1, "Root", "Container", null) + .AddTopic(2, "Web", "Page", 1) + .AddTopic(3, "Web_0", "Page", 2) + .AddTopic(4, "Web_0_0", "Page", 3); + + var cache = new CachedTopicRepository(inner); + var root = await cache.Load("Root"); + var web = await cache.Load("Web"); + + var web00 = await cache.Load(4); + + Assert.NotNull(web00); + Assert.Equal("Web_0", web00.Parent?.Key); + Assert.Same(web, web00.Parent?.Parent); + Assert.Contains(web!.Children, child => child.Key == "Web_0"); + Assert.Same(root, web00.GetRootTopic()); + + } + + /*============================================================================================================================ + | TEST: LOAD: AFTER ATTACHED-BUT-UNINDEXED SUBTREE: RETURNS ATTACHED INSTANCE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Simulates the shape produced by , which attaches new topics to an + /// existing parent without raising (and thus without indexing them), then calls + /// for the leaf and confirms the cache returns + /// the existing instance rather than throwing. Ensures a single-node attachment doesn't crash, with the leaf itself + /// (incorrectly) skipped by MergeIntoCache's dedupe check before its rewire runs, so no collision occurs, while an + /// intermediate, unindexed ancestor ("Web_0") is not skipped: Its rewire collides with the identically keyed topic + /// already attached at that position, throwing . + /// + [Fact] + public async Task Load_AfterAttachedButUnindexedSubtree_ReturnsAttachedInstance() { + + var inner = new FakeSqlTopicRepository() + .AddTopic(1, "Root", "Container", null) + .AddTopic(2, "Web", "Page", 1) + .AddTopic(3, "Web_0", "Page", 2) + .AddTopic(4, "Web_0_0", "Page", 3); + + var cache = new CachedTopicRepository(inner); + var web = await cache.Load("Web"); + + // Attach a two-level subtree directly, bypassing Load()/TopicLoaded—mirroring Refresh()'s attach-without-index shape + var newWeb0 = new Topic("Web_0", "Page", web, 3); + var newWeb00 = new Topic("Web_0_0", "Page", newWeb0, 4); + + var loaded = await cache.Load(4); + + Assert.Same(newWeb00, loaded); + Assert.Same(newWeb0, loaded?.Parent); + Assert.Same(web, loaded?.Parent?.Parent); + + } + + /*============================================================================================================================ + | TEST: ENSURE LOADED: DEFERRED ASSOCIATION FALLBACK WITH RESIDENT TARGET PARENT: ATTACHES RESOLVED TARGET + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Confirms that a deferred-association fallback ( + /// calling Load(targetId) with default, parameters) resolves a target whose direct parent + /// is already resident—the same shape as Defect 1—so the resolved instance attaches to the live cache graph rather than + /// arriving dangling. + /// + [Fact] + public async Task EnsureLoaded_DeferredAssociationFallbackWithResidentTargetParent_AttachesToCacheGraph() { + + var inner = new FakeSqlTopicRepository() + .AddTopic(1, "Root", "Container", null) + .AddTopic(2, "Web", "Page", 1) + .AddTopic(3, "Web_0", "Page", 2) + .AddTopic(4, "Web_0_0", "Page", 3) + .AddTopic(5, "Web_1", "Page", 2); + + inner.AddRelationship(5, "Related", 4); + + var cache = new CachedTopicRepository(inner); + var root = await cache.Load("Root"); + + // Establish "Web_0" (id 3) as resident—the direct parent of the deferred target + var web0 = await cache.Load("Web:Web_0"); + + var web1 = await cache.Load("Web:Web_1"); + var rawWeb1 = (ITopicBackingAccessor)web1!; + + Assert.NotEmpty(rawWeb1.Relationships.Deferred); + + await ((ITopicLazyLoadable)web1!).EnsureLoaded(TopicPayload.Relationships, cancellationToken: CancellationToken); + + var related = web1.Relationships.GetValues("Related").Single(); + + Assert.Same(web0, related.Parent); + Assert.Contains(web0!.Children, child => child.Id == related.Id); + Assert.Same(root, related.GetRootTopic()); + + } + +} //Class \ No newline at end of file From 10c51445696b5e3942c222b287f15cfce7cbc046 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Mon, 20 Jul 2026 14:40:39 -0700 Subject: [PATCH 214/337] Remove `includeExternalReferences` parameter The `includeExternalReferences` is unnecessary because a) this data is already returned regardless, b) if there isn't a topic graph via `referenceTopic`, the resolution is cheap, c) any failed resolution now ends up in the `Relationships.Deferred` collection, and d) this is more consistent with `topic.References`, which is otherwise analogous with relationships, except in this case. Regardless, this simplifies the `LoadTopicGraph()` signature while adding, at most, a very trivial loop against the already-provided That said, there's a preexisting bug here in that this was only used by the `ITopicRepository.Load()` overload for loading previous versions. But we don't want to wire up the topic to the existing topic graph when it's loaded, at least until it's actually rolled back, as otherwise we'd potentially end up with a legacy topic infecting the `IncomingRelationships` of topics in the live graph. At most, this is intended for a potential preview operation before a rollback, but the `ITopicRepository.Rollback()` method. But that'll be addressed in a subsequent fix. --- OnTopic.Data.Sql/SqlDataReaderExtensions.cs | 12 ++---------- OnTopic.Data.Sql/SqlTopicRepository.cs | 6 +----- 2 files changed, 3 insertions(+), 15 deletions(-) diff --git a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs index 2d95851c..71fce0df 100644 --- a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs +++ b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs @@ -52,11 +52,6 @@ internal static class SqlDataReaderExtensions { /// behavior is overwritten to accept whatever value is submitted. This can be used, for instance, to prevent an update /// from being persisted to the data store on . /// - /// - /// Optionally disables populating external references such as and . This is useful for cases where it's known that a shallow copy is being retrieved, and - /// thus external references aren't likely to be available. - /// /// An optional token that can be used to cancel the operation. /*============================================================================================================================ | METHOD: LOAD TOPIC GRAPH @@ -66,7 +61,6 @@ internal static class SqlDataReaderExtensions { int seedTopicId = -1, Topic? referenceTopic = null, bool? markDirty = null, - bool includeExternalReferences = true, CancellationToken cancellationToken = default ) { @@ -164,10 +158,8 @@ internal static class SqlDataReaderExtensions { await reader.NextResultAsync(cancellationToken).ConfigureAwait(false); // Loop through each relationship; multiple records may exist per topic - if (includeExternalReferences) { - while (await reader.ReadAsync(cancellationToken).ConfigureAwait(false)) { - reader.SetRelationships(topics, markDirty); - } + while (await reader.ReadAsync(cancellationToken).ConfigureAwait(false)) { + reader.SetRelationships(topics, markDirty); } /*-------------------------------------------------------------------------------------------------------------------------- diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index 47f44bea..188bb254 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -267,11 +267,7 @@ public SqlTopicRepository(string connectionString) { } // Load the historical version into the current topic graph - topic = await reader.LoadTopicGraph( - topicId, - referenceTopic, - includeExternalReferences: referenceTopic is not null - ).ConfigureAwait(false); + topic = await reader.LoadTopicGraph(topicId, referenceTopic).ConfigureAwait(false); } From eb15c3dd445157fcd4689f843306570192975973 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Mon, 20 Jul 2026 19:48:16 -0700 Subject: [PATCH 215/337] Added `IsDirty` concept to `DeferredAssociation` MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Previously, `DeferredAssociation` only logically happened if IDs were returned from the persistence layer, but not (yet) attached to the topic graph—and, as a result, were always clean. But that misses the case of `Rollback()`. There are a few approaches to solving this—such as forcing a full resolve before saving—but the easiest is to simply make the already centralized `DeferredAssociation` dirty-aware, so we can mark items as dirty if they're being merged as part of the version rollback. Included an optional `isDirty` parameter to `DeferredAssociationCollection.SetValue()` in order to set this value on new `DeferredAssociation` entries. This relates to a side-affect of the lazy-loading implementation (#111), which first introduced the concept of deferred associations (687d1ef9, f210866e). --- OnTopic/Associations/DeferredAssociation.cs | 10 ++++++++-- OnTopic/Associations/DeferredAssociationCollection.cs | 5 +++-- 2 files changed, 11 insertions(+), 4 deletions(-) diff --git a/OnTopic/Associations/DeferredAssociation.cs b/OnTopic/Associations/DeferredAssociation.cs index ab186e6b..138bf707 100644 --- a/OnTopic/Associations/DeferredAssociation.cs +++ b/OnTopic/Associations/DeferredAssociation.cs @@ -18,8 +18,14 @@ namespace OnTopic.Associations; /// This is exposed via and /// so that the can record missing associations during a load, and then can dynamically load /// them later when the collection is called. - /// /// The relationship or reference key under which the association is registered. /// The of the target topic to be resolved. -public record DeferredAssociation(string Key, int TopicId); \ No newline at end of file +/// +/// Whether the association should be marked as dirty once resolved, so that persists it. Defaults to false, which is appropriate for associations recorded during an ordinary load, where +/// the target is presumed to already reflect the persistence store and resolving it later shouldn't be treated as a pending +/// change. Associations representing a not-yet-persisted change are marked true, such as those transplanted by . +/// +public record DeferredAssociation(string Key, int TopicId, bool IsDirty = false); \ No newline at end of file diff --git a/OnTopic/Associations/DeferredAssociationCollection.cs b/OnTopic/Associations/DeferredAssociationCollection.cs index ce375b3f..9d1f3717 100644 --- a/OnTopic/Associations/DeferredAssociationCollection.cs +++ b/OnTopic/Associations/DeferredAssociationCollection.cs @@ -51,9 +51,10 @@ public DeferredAssociationCollection(bool singleValued = false) { /// /// The relationship or reference key under which the association is registered. /// The of the target topic to be resolved. - public void SetValue(string key, int topicId) { + /// Determines that the deferred entry is a modification yet to be saved. + public void SetValue(string key, int topicId, bool isDirty = false) { Remove(key, _singleValued? null : topicId); - Add(new(key, topicId)); + Add(new(key, topicId, isDirty)); } /*============================================================================================================================ From 41be0d8cd9174efa40a7f5f80a01df0e5794401c Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 21 Jul 2026 17:26:04 -0700 Subject: [PATCH 216/337] Introduce `ReplaceAll()` for deferred associations This allows all deferred associations to be replaced with a new set. This is specifically useful for `Rollback()`, where we need to update an existing topic to a prior topic's state. This includes setting each new `DeferredAssociation` to `isDirty` (eb15c3dd) since these are modifications from the fresh, loaded state. This relates to a side-affect of the lazy-loading implementation (#111), which first introduced the concept of deferred associations (687d1ef9, f210866e). --- .../DeferredAssociationCollection.cs | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/OnTopic/Associations/DeferredAssociationCollection.cs b/OnTopic/Associations/DeferredAssociationCollection.cs index 9d1f3717..f6a88eff 100644 --- a/OnTopic/Associations/DeferredAssociationCollection.cs +++ b/OnTopic/Associations/DeferredAssociationCollection.cs @@ -84,4 +84,29 @@ public bool Remove(string key, int? topicId = null) { return removed; } + /*============================================================================================================================ + | METHOD: REPLACE ALL + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Replaces every entry in the collection with the supplied , marking each as regardless of the source entry's own value. + /// + /// + /// Intended for merging a detached topic's deferred associations onto a live topic's own or wholesale, without requiring + /// the caller to individually clear and then for each entry. Every entry is + /// marked dirty because, by definition, a caller merging a new source into a resident collection is introducing a change + /// that isn't yet reflected in the persistence store, even though 's own entries are themselves + /// presumed clean in their original context (e.g., a detached historical version, freshly loaded from the persistence store + /// as-is). Because associations are saved wholesale, there's no attempt to differentiate between preexisting and genuine + /// changes as would be required for e.g., Indexed Attributes, which are only persisted if they are individually dirty. + /// + /// The entries to populate the collection with. + internal void ReplaceAll(IEnumerable source) { + Clear(); + foreach (var entry in source) { + SetValue(entry.Key, entry.TopicId, isDirty: true); + } + } + } //Class \ No newline at end of file From 03445b3e65d0632bc9485e7b5f670dfc9fb488b6 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 21 Jul 2026 20:36:18 -0700 Subject: [PATCH 217/337] Implement `IsDirty` in `ResolveAssociations()` With the introduction of `DeferredAssociation.IsDirty` (eb15c3dd), ensure that the property is set when resolving associations, so that a dirty deferred association is translated into a dirty association. This relates to a side-affect of the lazy-loading implementation (#111), which first introduced the concept of deferred associations (687d1ef9, f210866e). --- OnTopic/Repositories/LazyLoadingTopicRepository.cs | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/OnTopic/Repositories/LazyLoadingTopicRepository.cs b/OnTopic/Repositories/LazyLoadingTopicRepository.cs index 441941bc..336ca3de 100644 --- a/OnTopic/Repositories/LazyLoadingTopicRepository.cs +++ b/OnTopic/Repositories/LazyLoadingTopicRepository.cs @@ -121,9 +121,13 @@ protected Task ResolveAssociations(Topic topic, TopicPayload payload) { /// /// /// The shared core behind both ( : unresolvable targets are treated as stale and discarded) and ( : a - /// miss is left deferred for a later fallback); the two differ only in that flag. + /// name="fallBackToLoad"/> : unresolvable targets are treated as stale and discarded) and ( : a + /// miss is left deferred for a later fallback); the two differ only in that flag. Each resolved association is marked dirty + /// according to its own , rather than a flag supplied by the caller, so + /// associations that represent an unpersisted change (see e.g., ) are + /// correctly persisted by , while those recorded during an ordinary load + /// are not. /// /// The topic whose deferred associations should be resolved. /// @@ -156,7 +160,7 @@ private async Task ResolveAssociations(Topic topic, TopicPayload payload, bool f foreach (var deferred in rawTopic.Relationships.Deferred.ToArray()) { // SetValue removes the matching Deferred entry; any left unresolved are optionally cleared below if (await resolveTarget(deferred.TopicId).ConfigureAwait(false) is { } target) { - rawTopic.Relationships.SetValue(deferred.Key, target, markDirty: false); + rawTopic.Relationships.SetValue(deferred.Key, target, markDirty: deferred.IsDirty); } } if (fallBackToLoad) { @@ -169,7 +173,7 @@ private async Task ResolveAssociations(Topic topic, TopicPayload payload, bool f foreach (var deferred in rawTopic.References.Deferred.ToArray()) { // SetValue removes the matching Deferred entry; any left unresolved are optionally cleared below if (await resolveTarget(deferred.TopicId).ConfigureAwait(false) is { } target) { - rawTopic.References.SetValue(deferred.Key, target, markDirty: false); + rawTopic.References.SetValue(deferred.Key, target, markDirty: deferred.IsDirty); } } if (fallBackToLoad) { From 7bfd09e0041a6ee1c551f61315717a3b87cb744f Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 21 Jul 2026 20:47:38 -0700 Subject: [PATCH 218/337] Bug fix: Ensure reciprocal relationships removed Previously, when a relationship set was cleared using `TopicRelationshipMultiMap.Clear()`, the relationships were correctly removed from the immediate collection, but the reciprocal relationship weren't removed from the `IncomingRelationships`. As a result, anything relying on `IncomingRelationships` would continue to show the now-stale relationships. This fixes that bug by calling `Remove()` for each relationship, since `Remove()` already has the preexisting `MarkAs()` logic, as well as the ability to (conditionally) delete reciprocal relationships in their `IncomingRelationships` collections. While I was at it, I also simplified the logic since it was overly defensive; `GetValues()` will return an empty collection if the key doesn't exist or is empty. --- OnTopic/Associations/TopicRelationshipMultiMap.cs | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/OnTopic/Associations/TopicRelationshipMultiMap.cs b/OnTopic/Associations/TopicRelationshipMultiMap.cs index 37057749..b170d803 100644 --- a/OnTopic/Associations/TopicRelationshipMultiMap.cs +++ b/OnTopic/Associations/TopicRelationshipMultiMap.cs @@ -58,17 +58,15 @@ internal TopicRelationshipMultiMap(Topic parent, bool isIncoming = false): base( /// /// /// If there are any objects in the specified , then the will be marked as . + /// "TopicRelationshipMultiMap"/> will be marked as . Delegates to for each entry so the reciprocal relationship is also removed from each target's . /// /// The key of the relationship to be cleared. public void Clear(string relationshipKey) { Contract.Requires(!String.IsNullOrWhiteSpace(relationshipKey), nameof(relationshipKey)); - if (_storage.Contains(relationshipKey)) { - var relationship = _storage.GetValues(relationshipKey); - if (relationship.Count > 0) { - _dirtyKeys.MarkAs(relationshipKey, markDirty: !_parent.IsNew); - } - _storage.Clear(relationshipKey); + foreach (var topic in _storage.GetValues(relationshipKey).ToArray()) { + Remove(relationshipKey, topic); } } From 2589d79cbecd20f3bd033f45695d6e5ec111b95c Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 21 Jul 2026 20:52:25 -0700 Subject: [PATCH 219/337] Introduce `Clear()` for `Topic.Relationships` This adds a new internal `Clear()` method to `TopicRelationshipMultiMap`, which is used to `Topic.Relationships`, so that all relationships can be removed at one time, while also taking advantage of the ability to handle both `isDirty` and reciprocal relationships (7bfd09e0). This will be used by a refactoring to centralize the merging of version data. --- OnTopic/Associations/TopicRelationshipMultiMap.cs | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/OnTopic/Associations/TopicRelationshipMultiMap.cs b/OnTopic/Associations/TopicRelationshipMultiMap.cs index b170d803..5aa422bc 100644 --- a/OnTopic/Associations/TopicRelationshipMultiMap.cs +++ b/OnTopic/Associations/TopicRelationshipMultiMap.cs @@ -53,6 +53,19 @@ internal TopicRelationshipMultiMap(Topic parent, bool isIncoming = false): base( /*============================================================================================================================ | METHOD: CLEAR \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Removes every object across all relationship keys. + /// + /// + /// Delegates to for each key, which handles both the isDirty as well as the removal of + /// reciprocal relationships in . + /// + internal void Clear() { + foreach (var key in Keys) { + Clear(key); + } + } + /// /// Removes all objects grouped by a specific . /// From 142b9665ce29e6ee6388d727a4e69064596544ef Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 21 Jul 2026 21:42:01 -0700 Subject: [PATCH 220/337] Moved version merging into `Rollback()` Previously, the `Load(topicId, version, referenceTopic)` on `SqlTopicRepository` would not only load the historical version from the Microsoft SQL Database, but also merge it into the topic graph. That prevented it from being used to e.g., preview a previous version, and forced the live topic graph into accepting the loaded version without committing to doing a `Rollback()`. This update moves that logic to `Rollback()` itself so that `Load(topicId, version, referenceTopic)` is exclusively intended to load the historical version, without any relationship to the current topic graph, and then `Rollback()` is exclusively responsible for merging it into the live topic graph and committing the rollback to the persistence layer. As part of this, the logic for handling that merging is now moved out of `SqlTopicRepository` and into `TopicRepository`, via a new private `MergeVersion()` method, which means that logic can now be shared by any future implementations of `ITopicRepository` that derive from `TopicRepository` (as any interfacing with a persistence are expected to do). That simplifies the implementation of `SqlTopicRepository` and facilitates code reuse. As a result of this, the `referenceTopic` actually serves no purpose anymore; in a subsequent update, it will be removed from the overload. --- OnTopic.Data.Sql/SqlTopicRepository.cs | 52 +++------------ OnTopic/Repositories/ITopicRepository.cs | 29 +++++--- OnTopic/Repositories/TopicRepository.cs | 84 +++++++++++++++++++++++- 3 files changed, 112 insertions(+), 53 deletions(-) diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index 188bb254..12ce5fb8 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -200,6 +200,12 @@ public SqlTopicRepository(string connectionString) { /// public override async Task Load(int topicId, DateTime version, Topic? referenceTopic = null) { + /// + /// Always returns a detached graph, populated exclusively from the historical dataset; it is never + /// merged into a resident graph, and relationship and reference targets are left in Deferred rather than resolved. + /// Callers that need a historical version merged into a live to e.g., commit a rollback should use instead, which performs that merge before persisting the result. + /// /*-------------------------------------------------------------------------------------------------------------------------- | Normalize parameters @@ -216,24 +222,10 @@ public SqlTopicRepository(string connectionString) { ); /*-------------------------------------------------------------------------------------------------------------------------- - | Clear associations - >------------------------------------------------------------------------------------------------------------------------- - | Because we don't (currently) track version as part of the .NET data model for relationships or topic references, there's - | no easy way to determine if an association should be deleted when doing a rollback. As such, existing associations - | should be deleted, assuming a `referenceTopic` is passed, and it contains the `topicId`. + | Establish database connection \-------------------------------------------------------------------------------------------------------------------------*/ var topic = (Topic?)null; - if (referenceTopic?.Id == topicId) { - topic = referenceTopic; - } - else if (referenceTopic is not null) { - topic = referenceTopic.GetRootTopic().FindFirst(t => t.Id == topicId); - } - - /*-------------------------------------------------------------------------------------------------------------------------- - | Establish database connection - \-------------------------------------------------------------------------------------------------------------------------*/ using var connection = new SqlConnection(_connectionString); using var command = new SqlCommand("GetTopicVersion", connection) { CommandType = CommandType.StoredProcedure, @@ -255,19 +247,8 @@ public SqlTopicRepository(string connectionString) { await connection.OpenAsync().ConfigureAwait(false); using var reader = (SqlDataReader)await command.ExecuteReaderAsync().ConfigureAwait(false); - // Clear existing associations before repopulating from the historical version - if (topic is not null) { - var rawExisting = (ITopicBackingAccessor)topic; - foreach (var relationship in rawExisting.Relationships) { - rawExisting.Relationships.Clear(relationship.Key); - } - rawExisting.Relationships.Deferred.Clear(); - rawExisting.References.Deferred.Clear(); - rawExisting.References.Clear(); - } - - // Load the historical version into the current topic graph - topic = await reader.LoadTopicGraph(topicId, referenceTopic).ConfigureAwait(false); + // Load the historical version as a detached topic + topic = await reader.LoadTopicGraph(topicId).ConfigureAwait(false); } @@ -285,21 +266,6 @@ public SqlTopicRepository(string connectionString) { throw new TopicNotFoundException(topicId); } - /*-------------------------------------------------------------------------------------------------------------------------- - | Delete orphaned attributes - >------------------------------------------------------------------------------------------------------------------------- - | If a referenceTopic is passed, and it contains the `topicId`, then that instance will be updated with the previous - | version. In that case, however, any attributes which were first introduced after that version won't be overwritten. - | That's because there isn't a previous value associated with that key to overwrite the current value. In those cases, - | those attributes must be manually removed. - \-------------------------------------------------------------------------------------------------------------------------*/ - var rawTopic = (ITopicBackingAccessor)topic; - var orphanedAttributes = rawTopic.Attributes.Where(a => a.LastModified > version).ToList(); - - foreach (var attribute in orphanedAttributes) { - rawTopic.Attributes.Remove(attribute.Key); - } - /*-------------------------------------------------------------------------------------------------------------------------- | Raise event \-------------------------------------------------------------------------------------------------------------------------*/ diff --git a/OnTopic/Repositories/ITopicRepository.cs b/OnTopic/Repositories/ITopicRepository.cs index 97c7bf1c..38e4afe5 100644 --- a/OnTopic/Repositories/ITopicRepository.cs +++ b/OnTopic/Repositories/ITopicRepository.cs @@ -3,6 +3,7 @@ | Client Ignia, LLC | Project Topics Library \=============================================================================================================================*/ +using OnTopic.Associations; using OnTopic.Metadata; namespace OnTopic.Repositories; @@ -145,12 +146,18 @@ public interface ITopicRepository { Task Load(string? uniqueKey, bool isRecursive); /// - /// Loads a specific version of a based on its and . + /// Loads a specific version of a based on its and + /// as a detached topic, disconnected from any graph, with no , no , and no resolved relationships or references. /// /// - /// This overload does not accept an argument for recursion; it will only load a single instance of a version. Further, - /// it will only load versions for which the unique identifier is known. + /// + /// This overload is suitable for previewing a historical version; merging one into a live and + /// persisting the result is the responsibility of . + /// + /// + /// This overload does not accept an argument for recursion; it will only load a single instance of a version. + /// /// /// The topic identifier. /// The version. @@ -158,18 +165,24 @@ public interface ITopicRepository { /// When loading a single topic or branch, offers a reference topic graph that can be used to ensure that topic /// associations—such as references, relationships, and —are integrated with existing entities. /// - /// A topic object. Task Load(int topicId, DateTime version, Topic? referenceTopic = null); + /// A detached topic object. - /// + /// + /// A convenience overload of for callers that already have a + /// instance in hand. + /// + /// The current version of the whose history is being requested. + /// The version. + /// A detached topic object. Task Load(Topic topic, DateTime version); /*============================================================================================================================ | METHOD: ROLLBACK \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Rolls back the supplied to a particular point in its version history by reloading legacy - /// attributes and then saving the new version. + /// Rolls back the supplied to a particular point in its version history by merging the + /// historical version into it, and then saving the result as a new version. /// /// The current version of the to rollback. /// The selected Date/Time for the version to which to roll back. diff --git a/OnTopic/Repositories/TopicRepository.cs b/OnTopic/Repositories/TopicRepository.cs index 77820781..be1d8464 100644 --- a/OnTopic/Repositories/TopicRepository.cs +++ b/OnTopic/Repositories/TopicRepository.cs @@ -233,6 +233,12 @@ protected ContentTypeDescriptorCollection SetContentTypeDescriptors(ContentTypeD | METHOD: ROLLBACK \---------------------------------------------------------------------------------------------------------------------------*/ /// + /// + /// Merges the detached topic returned by into using , then resolves whatever relationships and references are already loaded in 's graph via , leaving + /// the rest deferred for lazy loading, before committing the result via . + /// public override async Task Rollback([ValidatedNotNull]Topic topic, DateTime version) { /*-------------------------------------------------------------------------------------------------------------------------- @@ -246,9 +252,27 @@ public override async Task Rollback([ValidatedNotNull]Topic topic, DateTime vers ); /*-------------------------------------------------------------------------------------------------------------------------- - | Retrieve topic from database + | Retrieve historical version + \-------------------------------------------------------------------------------------------------------------------------*/ + var historicalTopic = await Load(topic, version).ConfigureAwait(false)?? throw new TopicNotFoundException(topic.Id); + + /*-------------------------------------------------------------------------------------------------------------------------- + | Merge historical version into the live topic + >--------------------------------------------------------------------------------------------------------------------------- + | Some ITopicRepository implementations (e.g., test doubles backed by a single resident graph) may return the same instance + | from Load(Topic, DateTime); in that case, there's nothing to merge. \-------------------------------------------------------------------------------------------------------------------------*/ - await Load(topic, version).ConfigureAwait(false); + if (!ReferenceEquals(historicalTopic, topic)) { + MergeVersion(topic, historicalTopic); + } + + /*-------------------------------------------------------------------------------------------------------------------------- + | Resolve associations against the resident graph + >------------------------------------------------------------------------------------------------------------------------- + | Every entry MergeVersion() placed into Deferred is marked IsDirty via ReplaceAll(), so resolving them here also marks the + | corresponding Relationships and References dirty, ensuring Save() detects and persists them. + \-------------------------------------------------------------------------------------------------------------------------*/ + await ResolveAssociations(topic, TopicPayload.Relationships | TopicPayload.References).ConfigureAwait(false); /*-------------------------------------------------------------------------------------------------------------------------- | Save as new version @@ -954,4 +978,60 @@ private static void ResetAttributeDescriptors(Topic topic) { } } + + /*============================================================================================================================ + | METHOD: MERGE VERSION + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Merges the attributes, relationships, and references of a detached , as returned by + /// , onto the live it corresponds to. + /// + /// + /// Relationships and references are replaced wholesale: Each collection's Clear() empties the resolved half + /// (including reciprocal associations on previously related topics, e.g., ), then + /// 's Deferred entries are written onto 's Deferred + /// collections, marked dirty, ready for + /// to reconnect against whatever is already present in 's graph. Only Deferred needs to be + /// read, not any resolved associations on , because + /// is contractually incapable of resolving associations: With no referenceTopic parameter, it has no graph to + /// resolve them against, so every association it returns is, by construction, Deferred. + /// + /// The live to merge the historical version into. + /// The detached historical version, as returned by . + private static void MergeVersion(Topic topic, Topic historicalTopic) { + + /*-------------------------------------------------------------------------------------------------------------------------- + | Setup + \-------------------------------------------------------------------------------------------------------------------------*/ + var rawTopic = (ITopicBackingAccessor)topic; + var rawHistoricalTopic = (ITopicBackingAccessor)historicalTopic; + + /*-------------------------------------------------------------------------------------------------------------------------- + | Merge attributes + \-------------------------------------------------------------------------------------------------------------------------*/ + foreach (var attribute in rawHistoricalTopic.Attributes) { + rawTopic.Attributes.SetValue(attribute.Key, attribute.Value, isExtendedAttribute: attribute.IsExtendedAttribute); + } + + // Remove attributes that were introduced after the requested version + foreach (var attribute in rawTopic.Attributes.ToArray()) { + if (!rawHistoricalTopic.Attributes.Contains(attribute.Key)) { + rawTopic.Attributes.Remove(attribute.Key); + } + } + + /*-------------------------------------------------------------------------------------------------------------------------- + | Merge relationships + \-------------------------------------------------------------------------------------------------------------------------*/ + rawTopic.Relationships.Clear(); + rawTopic.Relationships.Deferred.ReplaceAll(rawHistoricalTopic.Relationships.Deferred); + + /*-------------------------------------------------------------------------------------------------------------------------- + | Merge references + \-------------------------------------------------------------------------------------------------------------------------*/ + rawTopic.References.Clear(); + rawTopic.References.Deferred.ReplaceAll(rawHistoricalTopic.References.Deferred); + + } + } //Class \ No newline at end of file From f22adb7acadb96d7c2dcc5691ffd696b5c4868ab Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 21 Jul 2026 21:51:01 -0700 Subject: [PATCH 221/337] Removed legacy `referenceTopic` parameter The `referenceTopic` was needed on the `ITopicRepository`'s `Load(topicId, version, referenceTopic)` because, previously, it not only loaded the topic into memory, but optionally merged it with any in-memory topic graph. With the merging now properly migrated to `Rollback()` (142b9665), and this overload only being responsible for returning a fully-detached historical version of a topic, this is no longer used, and can safely be removed from the signature. (This is obviously a breaking change for the public API, and will sit alongside other breaking changes for this major release.) As part of this, I also made significant updates to the documentation to `ITopicRepository` to better clarify the intent and distribution of labor between `Load()` and `Rollback()`. This not only helps with the migration, but should remain useful for future consumers of the API. This also allows us to entirely get rid of the overload in `CachedTopicRepository` since it no longer needs to intercept the request to pass the cache down to the base (a54bebdd). --- .../Repositories/StubTopicRepository.cs | 2 +- OnTopic.Data.Caching/CachedTopicRepository.cs | 28 ++----------------- OnTopic.Data.Sql/SqlTopicRepository.cs | 2 +- OnTopic.TestDoubles/DummyTopicRepository.cs | 2 +- .../StubLazyLoadingTopicRepository.cs | 4 +-- OnTopic.TestDoubles/StubTopicRepository.cs | 2 +- OnTopic.Tests/TopicRepositoryBaseTest.cs | 8 +++--- OnTopic/Repositories/ITopicRepository.cs | 23 +++++++++++---- .../Repositories/ObservableTopicRepository.cs | 2 +- OnTopic/Repositories/TopicRepository.cs | 2 +- .../Repositories/TopicRepositoryDecorator.cs | 4 +-- 11 files changed, 34 insertions(+), 45 deletions(-) diff --git a/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/Repositories/StubTopicRepository.cs b/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/Repositories/StubTopicRepository.cs index 27172960..73f45664 100644 --- a/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/Repositories/StubTopicRepository.cs +++ b/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/Repositories/StubTopicRepository.cs @@ -107,7 +107,7 @@ public StubTopicRepository() { } /// - public override Task Load(int topicId, DateTime version, Topic? referenceTopic = null) => + public override Task Load(int topicId, DateTime version) => throw new NotImplementedException(); /*============================================================================================================================ diff --git a/OnTopic.Data.Caching/CachedTopicRepository.cs b/OnTopic.Data.Caching/CachedTopicRepository.cs index b997e15d..47285330 100644 --- a/OnTopic.Data.Caching/CachedTopicRepository.cs +++ b/OnTopic.Data.Caching/CachedTopicRepository.cs @@ -16,8 +16,8 @@ namespace OnTopic.Data.Caching; /// Provides data access to topics stored in memory. /// /// -/// Concrete implementation of the class, which provides a wrapper -/// for an actual data access class. +/// Concrete implementation of the class, which provides a wrapper for an actual data access +/// class. /// public class CachedTopicRepository : TopicRepositoryDecorator, ITopicLazyLoader { @@ -233,30 +233,6 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos } - /// - public override async Task Load(int topicId, DateTime version, Topic? referenceTopic = null) { - - /*-------------------------------------------------------------------------------------------------------------------------- - | Normalize parameters - \-------------------------------------------------------------------------------------------------------------------------*/ - version = NormalizeToUtc(version); - - /*-------------------------------------------------------------------------------------------------------------------------- - | Validate parameters - \-------------------------------------------------------------------------------------------------------------------------*/ - Contract.Requires(version.Date < DateTime.UtcNow, "The version requested must be a valid historical date."); - Contract.Requires( - version.Date >= new DateTime(2014, 12, 9), - "The version is expected to have been created since version support was introduced into the topic library." - ); - - /*-------------------------------------------------------------------------------------------------------------------------- - | Return appropriate topic - \-------------------------------------------------------------------------------------------------------------------------*/ - return await TopicRepository.Load(topicId, version, referenceTopic ?? _cache).ConfigureAwait(false); - - } - /*============================================================================================================================ | METHODS: TOPIC LAZY LOADER \---------------------------------------------------------------------------------------------------------------------------*/ diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index 12ce5fb8..4b3c57a2 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -199,13 +199,13 @@ public SqlTopicRepository(string connectionString) { } /// - public override async Task Load(int topicId, DateTime version, Topic? referenceTopic = null) { /// /// Always returns a detached graph, populated exclusively from the historical dataset; it is never /// merged into a resident graph, and relationship and reference targets are left in Deferred rather than resolved. /// Callers that need a historical version merged into a live to e.g., commit a rollback should use instead, which performs that merge before persisting the result. /// + public override async Task Load(int topicId, DateTime version) { /*-------------------------------------------------------------------------------------------------------------------------- | Normalize parameters diff --git a/OnTopic.TestDoubles/DummyTopicRepository.cs b/OnTopic.TestDoubles/DummyTopicRepository.cs index 9e176590..38b80299 100644 --- a/OnTopic.TestDoubles/DummyTopicRepository.cs +++ b/OnTopic.TestDoubles/DummyTopicRepository.cs @@ -55,7 +55,7 @@ public DummyTopicRepository() { } public override Task Load(Topic? topic, DateTime version) => throw new NotImplementedException(); /// - public override Task Load(int topicId, DateTime version, Topic? referenceTopic = null) => throw new NotImplementedException(); + public override Task Load(int topicId, DateTime version) => throw new NotImplementedException(); /*============================================================================================================================ | METHOD: ROLLBACK diff --git a/OnTopic.TestDoubles/LazyLoading/StubLazyLoadingTopicRepository.cs b/OnTopic.TestDoubles/LazyLoading/StubLazyLoadingTopicRepository.cs index be812d63..ab45b757 100644 --- a/OnTopic.TestDoubles/LazyLoading/StubLazyLoadingTopicRepository.cs +++ b/OnTopic.TestDoubles/LazyLoading/StubLazyLoadingTopicRepository.cs @@ -212,7 +212,7 @@ await FillRequestedPayload( } /// - public override async Task Load(int topicId, DateTime version, Topic? referenceTopic = null) { + public override async Task Load(int topicId, DateTime version) { // Setup Contract.Requires(version.Date < DateTime.UtcNow, "The version requested must be a valid historical date."); @@ -222,7 +222,7 @@ await FillRequestedPayload( ); // Load the topic requested - var topic = await Load(topicId, referenceTopic).ConfigureAwait(false); + var topic = await Load(topicId).ConfigureAwait(false); // Throw an exception if the topic doesn't exist if (topic is null) { diff --git a/OnTopic.TestDoubles/StubTopicRepository.cs b/OnTopic.TestDoubles/StubTopicRepository.cs index 2015eb05..8f6650cb 100644 --- a/OnTopic.TestDoubles/StubTopicRepository.cs +++ b/OnTopic.TestDoubles/StubTopicRepository.cs @@ -112,7 +112,7 @@ public StubTopicRepository() { } /// - public override Task Load(int topicId, DateTime version, Topic? referenceTopic = null) { + public override Task Load(int topicId, DateTime version) { /*-------------------------------------------------------------------------------------------------------------------------- | Validate parameters diff --git a/OnTopic.Tests/TopicRepositoryBaseTest.cs b/OnTopic.Tests/TopicRepositoryBaseTest.cs index da754dc1..afe06710 100644 --- a/OnTopic.Tests/TopicRepositoryBaseTest.cs +++ b/OnTopic.Tests/TopicRepositoryBaseTest.cs @@ -125,7 +125,7 @@ public async Task Load_WithNarrowPayload_ExtendedAttributesLoaded() { | TEST: LOAD: VALID DATE: RETURNS TOPIC \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Calls with a valid date and ensures that topic + /// Calls with a valid date and ensures that topic /// with that date is returned. /// [Fact] @@ -166,7 +166,7 @@ public async Task Rollback_Topic_UpdatesLastModified() { | TEST: LOAD: FUTURE DATE: THROWS EXCEPTION \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Calls with a future and + /// Calls with a future and /// confirms that an exception is thrown. /// [Fact] @@ -179,7 +179,7 @@ await Assert.ThrowsAsync(() => | TEST: LOAD: OLD DATE: THROWS EXCEPTION \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Calls with a date prior to versioning being + /// Calls with a date prior to versioning being /// introduced and ensures that an exception is thrown. /// [Fact] @@ -1013,7 +1013,7 @@ public async Task Load_TopicLoadedEvent_IsRaised() { | TEST: LOAD: TOPIC LOADED EVENT: IS RAISED WITH VERSION \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Loads a topic using and ensures that the and ensures that the event is raised. /// [Fact] diff --git a/OnTopic/Repositories/ITopicRepository.cs b/OnTopic/Repositories/ITopicRepository.cs index 38e4afe5..37e04674 100644 --- a/OnTopic/Repositories/ITopicRepository.cs +++ b/OnTopic/Repositories/ITopicRepository.cs @@ -158,20 +158,27 @@ public interface ITopicRepository { /// /// This overload does not accept an argument for recursion; it will only load a single instance of a version. /// + /// + /// This overload also does not accept an argument for a reference topic and, as a result, which enforces the detachment: + /// Without that, an implementation has no resident graph to resolve relationships or references against, and so every + /// association the returned carries is, by construction, left in either or rather than resolved. + /// /// /// The topic identifier. /// The version. - /// - /// When loading a single topic or branch, offers a reference topic graph that can be used to ensure that topic - /// associations—such as references, relationships, and —are integrated with existing entities. - /// - Task Load(int topicId, DateTime version, Topic? referenceTopic = null); /// A detached topic object. + Task Load(int topicId, DateTime version); /// /// A convenience overload of for callers that already have a /// instance in hand. /// + /// + /// Returns the same detached preview graph does; it does not merge the result into + /// , or otherwise mutate it. Callers that need to commit a historical version onto a live should use instead. + /// /// The current version of the whose history is being requested. /// The version. /// A detached topic object. @@ -184,6 +191,12 @@ public interface ITopicRepository { /// Rolls back the supplied to a particular point in its version history by merging the /// historical version into it, and then saving the result as a new version. /// + /// + /// Unlike or , this mutates + /// in place, immediately followed by . It is not appropriate for + /// previewing a historical version; use for that, as it only load the version, without + /// incporating it into any in-memory topic graph or committing the previous version to the persistence store. + /// /// The current version of the to rollback. /// The selected Date/Time for the version to which to roll back. /// ? TopicRenamed { public abstract Task Load(Topic topic, DateTime version); /// - public abstract Task Load(int topicId, DateTime version, Topic? referenceTopic = null); + public abstract Task Load(int topicId, DateTime version); /*============================================================================================================================ | METHOD: REFRESH diff --git a/OnTopic/Repositories/TopicRepository.cs b/OnTopic/Repositories/TopicRepository.cs index be1d8464..25153ab1 100644 --- a/OnTopic/Repositories/TopicRepository.cs +++ b/OnTopic/Repositories/TopicRepository.cs @@ -226,7 +226,7 @@ protected ContentTypeDescriptorCollection SetContentTypeDescriptors(ContentTypeD $"The version '{version}' of '{topic.GetUniqueKey()}' cannot be loaded. Topics must be saved in order to load " + $"previous versions." ); - return Load(topic.Id, version, topic); + return Load(topic.Id, version); } /*============================================================================================================================ diff --git a/OnTopic/Repositories/TopicRepositoryDecorator.cs b/OnTopic/Repositories/TopicRepositoryDecorator.cs index da27e36e..4fc6f45d 100644 --- a/OnTopic/Repositories/TopicRepositoryDecorator.cs +++ b/OnTopic/Repositories/TopicRepositoryDecorator.cs @@ -102,8 +102,8 @@ protected TopicRepositoryDecorator(ITopicRepository topicRepository) { => TopicRepository.Load(topic, version); /// - public override Task Load(int topicId, DateTime version, Topic? referenceTopic = null) => - TopicRepository.Load(topicId, version, referenceTopic); + public override Task Load(int topicId, DateTime version) => + TopicRepository.Load(topicId, version); /*============================================================================================================================ | METHOD: REFRESH From 778fe9a13438ecea458135fb1ec875547972886f Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 21 Jul 2026 23:02:44 -0700 Subject: [PATCH 222/337] Ensure `Deferred` associations are persisted With the introduction of `Deferred` (ba72f235, fce368be, 520ce3c5, f210866e, c65307f5, 687d1ef9, f2add3ac) associations loaded don't necessarily need to be resolved to an associated topic in the topic graph, as they can be temporarily stored in `Deferred` awaiting resolution via e.g., `ResolveAssociations()` (167067f3) or `LoadDeferredAssociations` (b787626b , 1935995c , cf376a7f). But if the associations haven't been resolved, and `Save()` is called, that means those deferred associations won't be persisted. That's fine in a normal circumstance because only associations in `DeletedItems` will be deleted, and so any unresolved associations that came from the database will remain in the database. But it becomes a problem with the `Rollback()` logic (142b9665) since it may add items that can't be resolved in the current topic graph, but which also didn't exist in the previous version of the topic. To mitigate that, `Save()` is being updated to include `Deferred` associations in its mappings of both `Relationships` and `References`. This contributes to #111. --- OnTopic.Data.Sql/SqlTopicRepository.cs | 39 ++++++++++++++++++-------- 1 file changed, 27 insertions(+), 12 deletions(-) diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index 4b3c57a2..42114d86 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -811,13 +811,22 @@ private static void AddEnsureLoadedParameters(SqlCommand command, int topicId, T /// The SQL connection. private static async Task PersistRelationships(Topic topic, DateTime version, SqlConnection connection) { + /*-------------------------------------------------------------------------------------------------------------------------- + | Determine relationship keys to persist + >--------------------------------------------------------------------------------------------------------------------------- + | Includes keys with a dirty deferred entries merged in by Rollback() alongside resolved keys, so a target that hasn't been + | resolved to an in-memory Topic is still persisted by its Deferred TopicId, rather than being silently dropped since it + | isn't returned by Relationships.GetValues(). + \-------------------------------------------------------------------------------------------------------------------------*/ var rawTopic = (ITopicBackingAccessor)topic; + var dirtyDeferred = rawTopic.Relationships.Deferred.Where(deferred => deferred.IsDirty).ToList(); + var relationshipKeys = rawTopic.Relationships.Keys.Union(dirtyDeferred.Select(deferred => deferred.Key)).ToList(); /*-------------------------------------------------------------------------------------------------------------------------- | Return blank if the topic has no relations. \-------------------------------------------------------------------------------------------------------------------------*/ // return if the topic has no relations - if (rawTopic.Relationships.Keys.Count == 0) { + if (relationshipKeys.Count == 0) { return; } @@ -826,19 +835,26 @@ private static async Task PersistRelationships(Topic topic, DateTime version, Sq /*------------------------------------------------------------------------------------------------------------------------ | Iterate through each scope and persist to SQL \-----------------------------------------------------------------------------------------------------------------------*/ - foreach (var key in rawTopic.Relationships.Keys) { + foreach (var key in relationshipKeys) { + // Setup stored procedure using var targetIds = new TopicListDataTable(); using var command = new SqlCommand("UpdateRelationships", connection) { CommandType = CommandType.StoredProcedure }; + // Include resolved relationships foreach (var targetTopic in rawTopic.Relationships.GetValues(key)) { if (!targetTopic.IsNew) { targetIds.AddRow(targetTopic.Id); } } + // Include deferred relationships + foreach (var deferred in dirtyDeferred.Where(deferred => deferred.Key == key)) { + targetIds.AddRow(deferred.TopicId); + } + // Add Parameters command.AddParameter("TopicID", topic.Id.ToString(CultureInfo.InvariantCulture)); command.AddParameter("RelationshipKey", key); @@ -846,6 +862,7 @@ private static async Task PersistRelationships(Topic topic, DateTime version, Sq command.AddParameter("Version", version); command.AddParameter("DeleteUnmatched", rawTopic.Relationships.LoadState is LoadState.Loaded); + // Execute command await command.ExecuteNonQueryAsync().ConfigureAwait(false); } @@ -862,11 +879,6 @@ private static async Task PersistRelationships(Topic topic, DateTime version, Sq ); } - /*-------------------------------------------------------------------------------------------------------------------------- - | Return - \-------------------------------------------------------------------------------------------------------------------------*/ - return; - } /*============================================================================================================================ @@ -887,23 +899,31 @@ private static async Task PersistReferences(Topic topic, DateTime version, SqlCo \-------------------------------------------------------------------------------------------------------------------------*/ try { + // Setup stored procedure using var references = new TopicReferencesDataTable(); using var command = new SqlCommand("UpdateReferences", connection) { CommandType = CommandType.StoredProcedure }; + // Include resolved references foreach (var relatedTopic in rawTopic.References) { if (!relatedTopic.Value?.IsNew?? false) { references.AddRow(relatedTopic.Key, relatedTopic.Value!.Id); } } + // Include deferred references + foreach (var deferred in rawTopic.References.Deferred.Where(deferred => deferred.IsDirty)) { + references.AddRow(deferred.Key, deferred.TopicId); + } + // Add Parameters command.AddParameter("TopicID", topic.Id.ToString(CultureInfo.InvariantCulture)); command.AddParameter("ReferencedTopics", references); command.AddParameter("Version", version); command.AddParameter("DeleteUnmatched", rawTopic.References.LoadState is LoadState.Loaded); + // Execute the command await command.ExecuteNonQueryAsync().ConfigureAwait(false); } @@ -918,11 +938,6 @@ private static async Task PersistReferences(Topic topic, DateTime version, SqlCo ); } - /*-------------------------------------------------------------------------------------------------------------------------- - | Return - \-------------------------------------------------------------------------------------------------------------------------*/ - return; - } } //Class \ No newline at end of file From a70950070aff7ed55a2629f259e3a4be14ffbc18 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Wed, 22 Jul 2026 12:16:10 -0700 Subject: [PATCH 223/337] Updated documents regarding enumeration Because `Topic.Attributes` doesn't trigger lazy loading (#111) until `GetValue()` is called with a miss, it can be enumerators over without triggering lazy loading, unless `Topic.Relationships`, `Topic.References`, `Topic.Children`. and `Topic.VersionHistory`. This is normally fine, because there generally aren't a lot of legitimate use cases for iterating over attributes, but it's worth making note of for implementors. --- OnTopic/Attributes/AttributeCollection.cs | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/OnTopic/Attributes/AttributeCollection.cs b/OnTopic/Attributes/AttributeCollection.cs index dc51f217..e43a30b0 100644 --- a/OnTopic/Attributes/AttributeCollection.cs +++ b/OnTopic/Attributes/AttributeCollection.cs @@ -20,6 +20,14 @@ namespace OnTopic.Attributes; /// objects represent individual instances of attributes associated with particular topics. /// The class tracks these through its property, which is an instance of /// the class. +/// +/// When is , iterating the collection (e.g., via foreach, +/// LINQ operators, or ) returns only the indexed attributes already present and +/// does not fetch the deferred extended attribute blob. Only a keyed lookup autoloads on a miss. Callers that require a +/// complete set of attributes must first await with . Otherwise, a decision that depends on seeing every attribute may act on a partial +/// view without any error being raised. +/// /// public class AttributeCollection : TrackedRecordCollection { @@ -208,8 +216,9 @@ public void SetValue( /// /// /// The method will exclude attributes which correspond to properties on - /// which contain specialized getter logic, such as and . + /// which contain specialized getter logic, such as and . Like any enumeration over the collection, this reads only the resident attributes; see the remarks for the completeness contract on a topic. /// /// /// Determines if attributes from the should be included. Defaults to false. From 3cd78b3702dfbfb4f2454b17ffcde3d58944b73b Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Wed, 22 Jul 2026 14:14:56 -0700 Subject: [PATCH 224/337] Account for `Deferred` in `IsDirty()` With `Deferred` now being included in `PersistRelationships()` and `PersistReferences()` (778fe9a1), and `IsDirty` being applied as a property to `DeferredAssociation` (eb15c3dd, 03445b3e), it's important that the `IsDirty()` calculation on `TopicRelationshipMultiMap` (i.e., `Topic.Relationships`) and `TopicReferenceCollection` (i.e., `Topic.References`) reflect the presence of any dirty deferred assocaitions. --- OnTopic/Associations/TopicReferenceCollection.cs | 11 +++++++++++ OnTopic/Associations/TopicRelationshipMultiMap.cs | 7 ++++++- 2 files changed, 17 insertions(+), 1 deletion(-) diff --git a/OnTopic/Associations/TopicReferenceCollection.cs b/OnTopic/Associations/TopicReferenceCollection.cs index 032593b4..47787cd0 100644 --- a/OnTopic/Associations/TopicReferenceCollection.cs +++ b/OnTopic/Associations/TopicReferenceCollection.cs @@ -69,6 +69,17 @@ public TopicReferenceCollection(Topic parentTopic) : base(parentTopic) { } /// public DeferredAssociationCollection Deferred { get; } = new(singleValued: true); + /*============================================================================================================================ + | METHOD: IS DIRTY? + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// + /// Extends the base to also account for a dirty + /// entry introduced by e.g., , + /// so a reference that hasn't yet been resolved to an in-memory still marks the collection dirty. + /// + public override bool IsDirty() => base.IsDirty() || Deferred.Any(deferred => deferred.IsDirty); + /*============================================================================================================================ | INSERT ITEM \---------------------------------------------------------------------------------------------------------------------------*/ diff --git a/OnTopic/Associations/TopicRelationshipMultiMap.cs b/OnTopic/Associations/TopicRelationshipMultiMap.cs index 5aa422bc..94021454 100644 --- a/OnTopic/Associations/TopicRelationshipMultiMap.cs +++ b/OnTopic/Associations/TopicRelationshipMultiMap.cs @@ -230,7 +230,12 @@ public void SetValue(string relationshipKey, Topic topic, bool? markDirty = null | METHOD: IS DIRTY? \---------------------------------------------------------------------------------------------------------------------------*/ /// - public bool IsDirty() => _dirtyKeys.IsDirty(); + /// + /// Also accounts for any dirty entries as introduced by e.g., , so a relationship that hasn't yet been resolved to an in-memory still marks the collection as dirty. + /// + public bool IsDirty() => _dirtyKeys.IsDirty() || Deferred.Any(deferred => deferred.IsDirty); /// public bool IsDirty(string key) => _dirtyKeys.IsDirty(key); From 2986685d2d8962e2ca58d6afe98461cffddc5cf6 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Wed, 22 Jul 2026 14:32:20 -0700 Subject: [PATCH 225/337] Always persist associations w/ `@DeleteUnmatched` Now that we know all associations are accounted for on `Load()` via `Deferred` (ba72f235, fce368be, 520ce3c5, f210866e, c65307f5, 687d1ef9, f2add3ac), and `Deferred` items are now included when calling `PersistRelationships()` or `PersistReferences()` (778fe9a1), the gate for `@DeleteUnmatched` based on the deletion criteria no longer makes sense, as we always have all of the association data in a format suitable for the database, even if it's not all resolved within our in-memory graph. This addresses a gap in the initial implementation of the lazy-loading infrastructure (#111). --- OnTopic.Data.Sql/SqlTopicRepository.cs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index 42114d86..a3ce94af 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -851,7 +851,7 @@ private static async Task PersistRelationships(Topic topic, DateTime version, Sq } // Include deferred relationships - foreach (var deferred in dirtyDeferred.Where(deferred => deferred.Key == key)) { + foreach (var deferred in deferredByKey[key]) { targetIds.AddRow(deferred.TopicId); } @@ -860,7 +860,7 @@ private static async Task PersistRelationships(Topic topic, DateTime version, Sq command.AddParameter("RelationshipKey", key); command.AddParameter("RelatedTopics", targetIds); command.AddParameter("Version", version); - command.AddParameter("DeleteUnmatched", rawTopic.Relationships.LoadState is LoadState.Loaded); + command.AddParameter("DeleteUnmatched", true); // Execute command await command.ExecuteNonQueryAsync().ConfigureAwait(false); @@ -913,7 +913,7 @@ private static async Task PersistReferences(Topic topic, DateTime version, SqlCo } // Include deferred references - foreach (var deferred in rawTopic.References.Deferred.Where(deferred => deferred.IsDirty)) { + foreach (var deferred in rawTopic.References.Deferred) { references.AddRow(deferred.Key, deferred.TopicId); } @@ -921,7 +921,7 @@ private static async Task PersistReferences(Topic topic, DateTime version, SqlCo command.AddParameter("TopicID", topic.Id.ToString(CultureInfo.InvariantCulture)); command.AddParameter("ReferencedTopics", references); command.AddParameter("Version", version); - command.AddParameter("DeleteUnmatched", rawTopic.References.LoadState is LoadState.Loaded); + command.AddParameter("DeleteUnmatched", true); // Execute the command await command.ExecuteNonQueryAsync().ConfigureAwait(false); From cceae9e4798724f9e688ef73e325e3c9bf46f834 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Wed, 22 Jul 2026 14:37:47 -0700 Subject: [PATCH 226/337] Filter `PersistRelationships()` by `IsDirty` While we pass all associations, dirty or clean, to the `UpdateRelationships` stored procedure so that we can include the `@DeleteUnmatched` flag (), we should limit calling the `UpdateRelationships` stored procedure itself for keys that, indeed, have `IsDirty` associations, either resolved or unresolved. Previously, if any associations in `Topic.Relationships` were `IsDirty`, then each key made a separate roundtrip to SQL calling `UpdateRelationships`, even for keys that may not have any dirty relationships. This patches that gap, which can have a performance benefit when saving any topics with a lot of relationships. --- OnTopic.Data.Sql/SqlTopicRepository.cs | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index a3ce94af..5584cba8 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -814,13 +814,16 @@ private static async Task PersistRelationships(Topic topic, DateTime version, Sq /*-------------------------------------------------------------------------------------------------------------------------- | Determine relationship keys to persist >--------------------------------------------------------------------------------------------------------------------------- - | Includes keys with a dirty deferred entries merged in by Rollback() alongside resolved keys, so a target that hasn't been - | resolved to an in-memory Topic is still persisted by its Deferred TopicId, rather than being silently dropped since it - | isn't returned by Relationships.GetValues(). + | Limited to dirty keys, either resolved or deferred. Each key maps to its own UpdateRelationships call, scoped to that + | key's own TVP and DeleteUnmatched, so skipping a clean key here simply leaves its existing rows untouched in SQL, while a + | also ensuring any deleted keys are correctly accounted for. \-------------------------------------------------------------------------------------------------------------------------*/ var rawTopic = (ITopicBackingAccessor)topic; var dirtyDeferred = rawTopic.Relationships.Deferred.Where(deferred => deferred.IsDirty).ToList(); - var relationshipKeys = rawTopic.Relationships.Keys.Union(dirtyDeferred.Select(deferred => deferred.Key)).ToList(); + var relationshipKeys = rawTopic.Relationships.Keys + .Where(key => rawTopic.Relationships.IsDirty(key)) + .Union(dirtyDeferred.Select(deferred => deferred.Key)).ToList(); + var deferredByKey = rawTopic.Relationships.Deferred.ToLookup(deferred => deferred.Key); /*-------------------------------------------------------------------------------------------------------------------------- | Return blank if the topic has no relations. From ff134c0cc44963a6b507bcfd78a53400ad2386be Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Thu, 23 Jul 2026 18:00:28 -0700 Subject: [PATCH 227/337] Centralize `LoadTopicGraph()` with delegate We're going to need another entry points to `LoadTopicGraph()`. In preparation, I'm creating a local intermediary by the same name that accepts a delegate before passing the results on to the actual `SqlDataReader.LoadTopicGraph()`. This is being extracted from the existing `Load()` overload that previously did this work inline. This will contribute to the testing of the lazy-loading infrastructure (#111). --- .../TestDoubles/FakeSqlTopicRepository.cs | 62 ++++++++++++++----- 1 file changed, 48 insertions(+), 14 deletions(-) diff --git a/OnTopic.Tests/TestDoubles/FakeSqlTopicRepository.cs b/OnTopic.Tests/TestDoubles/FakeSqlTopicRepository.cs index 1b55914d..7fe9235d 100644 --- a/OnTopic.Tests/TestDoubles/FakeSqlTopicRepository.cs +++ b/OnTopic.Tests/TestDoubles/FakeSqlTopicRepository.cs @@ -122,21 +122,61 @@ private string GetUniqueKey(int id) { current = _rows[id].ParentId; } + // Delegate to the shared graph builder, seeded with the ascendant chain and current relationships + var topic = await LoadTopicGraph( + topicId, + referenceTopic, + populateTopics, + relationshipRows : _relationships.Where(r => chain.Contains(r.SourceId)) + ).ConfigureAwait(false); + + // Raise the TopicLoaded event + OnTopicLoaded(new(topic!, isRecursive)); + + // Finally, return the seed topic + return topic; + + // Populates the ascendant chain's rows into the source data table + void populateTopics(TopicsDataTable topics) { + foreach (var id in chain) { + var (key, contentType, parentId) = _rows[id]; + var hasChildren = _rows.Values.Any(row => row.ParentId == id); + topics.AddRow(id, key, contentType, parentId, hasChildren: hasChildren); + } + } + + } + + /*============================================================================================================================ + | METHOD: LOAD TOPIC GRAPH + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Builds a fresh set of and rows, then feeds them + /// through the real , exactly as does + /// from a live reader. + /// + /// The to seed the load with. + /// The reference topic graph to reconcile new rows against, if any. + /// Adds whatever topic row(s) the caller's scenario requires to the source data table. + /// The relationship rows to feed alongside the topic row(s). + private static async Task LoadTopicGraph( + int topicId, + Topic? referenceTopic, + Action populateTopics, + IEnumerable<(int SourceId, string Key, int TargetId)> relationshipRows + ) { + // Define source data tables using var topics = new TopicsDataTable(); using var attributes = new AttributesDataTable(); using var extendedAttributes = new AttributesDataTable(); using var relationships = new RelationshipsDataTable(); - // Build the descendant data - foreach (var id in chain) { - var (key, contentType, parentId) = _rows[id]; - var hasChildren = _rows.Values.Any(row => row.ParentId == id); - topics.AddRow(id, key, contentType, parentId, hasChildren: hasChildren); - } + // Build the topic data + populateTopics(topics); // Build the relationship data - foreach (var (sourceId, key, targetId) in _relationships.Where(r => chain.Contains(r.SourceId))) { + foreach (var (sourceId, key, targetId) in relationshipRows) { relationships.AddRow(sourceId, key, targetId, isDeleted: false); } @@ -144,18 +184,12 @@ private string GetUniqueKey(int id) { using var tableReader = new DataTableReader([topics, attributes, extendedAttributes, relationships]); // Delegate to the standard LoadTopicGraph from the SQL provider - var topic = await tableReader.LoadTopicGraph( + return await tableReader.LoadTopicGraph( topicId, referenceTopic, cancellationToken : CancellationToken.None ).ConfigureAwait(false); - // Raise the TopicLoaded event - OnTopicLoaded(new(topic!, isRecursive)); - - // Finally, return the seed topic - return topic; - } /// From 3e4e0192749393d3f0712a1c5842a66b1627f5a2 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Thu, 23 Jul 2026 18:09:51 -0700 Subject: [PATCH 228/337] Allow for registering historical relationships This will allow a future overload of `Load(topicId, version)` to use `LoadTopicGraph()` to test the loading (and even `Rollback()`) of prior versions. This will allow us to test the refactoring of dirty deferred associations (eb15c3dd, 41be0d8c, 03445b3e, 2589d79c, 3cd78b37), `Load(topicId, version)` (f22adb7a ) and the move to `Rollback()` (142b9665) in response to the lazy-loading framework (#111), as well as the related changes to `LoadTopicGraph()` (778fe9a1) and `SqlTopicRepository` (2986685d, cceae9e4) to support it . --- OnTopic.Tests/TestDoubles/FakeSqlTopicRepository.cs | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/OnTopic.Tests/TestDoubles/FakeSqlTopicRepository.cs b/OnTopic.Tests/TestDoubles/FakeSqlTopicRepository.cs index 7fe9235d..5a1b893f 100644 --- a/OnTopic.Tests/TestDoubles/FakeSqlTopicRepository.cs +++ b/OnTopic.Tests/TestDoubles/FakeSqlTopicRepository.cs @@ -38,6 +38,7 @@ internal sealed class FakeSqlTopicRepository : TopicRepository { \---------------------------------------------------------------------------------------------------------------------------*/ private readonly Dictionary _rows = []; private readonly List<(int SourceId, string Key, int TargetId)> _relationships = []; + private readonly List<(int SourceId, string Key, int TargetId)> _historicalRelationships = []; private readonly Dictionary _keyIndex = new(StringComparer.OrdinalIgnoreCase); private int _identity = 90000; @@ -63,6 +64,16 @@ public FakeSqlTopicRepository AddTopic(int id, string key, string contentType, i /// public void AddRelationship(int sourceId, string key, int targetId) => _relationships.Add((sourceId, key, targetId)); + /*============================================================================================================================ + | METHOD: ADD HISTORICAL RELATIONSHIP + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Registers a relationship row belonging to a historical version, returned independently of the current relationships + /// added by , and instead returned by a call to . + /// + public void AddHistoricalRelationship(int sourceId, string key, int targetId) => + _historicalRelationships.Add((sourceId, key, targetId)); + /*============================================================================================================================ | METHOD: GET UNIQUE KEY \---------------------------------------------------------------------------------------------------------------------------*/ From 30deeb34a70607f61d3135b6a23f90df9e7949e2 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Thu, 23 Jul 2026 18:14:05 -0700 Subject: [PATCH 229/337] Improved `Load(topicId, version)` fake This replaces the `Load(topicId, version)` to not just return a topic, but to actually test a versioning issue, at least in context o relationships using the newly introduced `LoadTopicGraph()` intermediary (ff134c0c) and `AddHistoricalRelationship()` test helper (3e4e0192). This will allow us to test the refactoring of dirty deferred associations (eb15c3dd, 41be0d8c, 03445b3e, 2589d79c, 3cd78b37), `Load(topicId, version)` (f22adb7a ) and the move to `Rollback()` (142b9665) in response to the lazy-loading framework (#111), as well as the related changes to `LoadTopicGraph()` (778fe9a1) and `SqlTopicRepository` (2986685d, cceae9e4) to support it . --- .../TestDoubles/FakeSqlTopicRepository.cs | 39 +++++++++++++++++-- 1 file changed, 35 insertions(+), 4 deletions(-) diff --git a/OnTopic.Tests/TestDoubles/FakeSqlTopicRepository.cs b/OnTopic.Tests/TestDoubles/FakeSqlTopicRepository.cs index 5a1b893f..8096d4ce 100644 --- a/OnTopic.Tests/TestDoubles/FakeSqlTopicRepository.cs +++ b/OnTopic.Tests/TestDoubles/FakeSqlTopicRepository.cs @@ -158,10 +158,45 @@ void populateTopics(TopicsDataTable topics) { } + /// + /// + /// Unlike , this builds a single-row , + /// without the ascendant chain, and populated from rather than , then feeds it through with noreferenceTopic + /// , mirroring production's detached GetTopicVersion: The returned has no and no resolved associations, only Deferred entries. + /// + public override async Task Load(int topicId, DateTime version) { + + // Bypass for rowstore misses + if (!_rows.TryGetValue(topicId, out var row)) { + return null; + } + + var (key, contentType, _) = row; + + // Delegate to the shared graph builder, seeded with a single disconnected row and no referenceTopic, per the detached + // contract, alongside historical rather than current relationships + var topic = await LoadTopicGraph( + topicId, + referenceTopic : null, + populateTopics : topics => topics.AddRow(topicId, key, contentType), + relationshipRows : _historicalRelationships.Where(r => r.SourceId == topicId) + ).ConfigureAwait(false); + + // Raise the TopicLoaded event + OnTopicLoaded(new(topic!, false, version)); + + // Finally, return the detached topic + return topic; + + } + /*============================================================================================================================ | METHOD: LOAD TOPIC GRAPH \---------------------------------------------------------------------------------------------------------------------------*/ /// + /// Shared core behind and : /// Builds a fresh set of and rows, then feeds them /// through the real , exactly as does /// from a live reader. @@ -203,10 +238,6 @@ void populateTopics(TopicsDataTable topics) { } - /// - public override async Task Load(int topicId, DateTime version, Topic? referenceTopic = null) => - await Load(topicId, referenceTopic).ConfigureAwait(false); - /*============================================================================================================================ | METHOD: REFRESH \---------------------------------------------------------------------------------------------------------------------------*/ From a0b2c3cb0465a91012e8818b0103ecdb09381ba9 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Thu, 23 Jul 2026 18:28:53 -0700 Subject: [PATCH 230/337] Added unit test for dirty deferred associations Previously, I added the `IsDirty` concept to `Deferred` associations (eb15c3dd) as well as their resolution (03445b3e). These tests ensure that `IsDirty` deferred associations resolve to `IsDirty` associations, and vice versa. This tests a resolution to a side-affect of the lazy-loading implementation (#111), which first introduced the concept of deferred associations (687d1ef9, f210866e). --- .../LazyLoadingTopicRepositoryTest.cs | 59 +++++++++++++++++++ 1 file changed, 59 insertions(+) diff --git a/OnTopic.Tests/LazyLoadingTopicRepositoryTest.cs b/OnTopic.Tests/LazyLoadingTopicRepositoryTest.cs index fffa7d2d..68616f0b 100644 --- a/OnTopic.Tests/LazyLoadingTopicRepositoryTest.cs +++ b/OnTopic.Tests/LazyLoadingTopicRepositoryTest.cs @@ -3,6 +3,7 @@ | Client Ignia, LLC | Project Topics Library \=============================================================================================================================*/ +using OnTopic.Associations; using OnTopic.Data.Caching; using OnTopic.Repositories; using OnTopic.TestDoubles.LazyLoading; @@ -758,4 +759,62 @@ public async Task Load_WholeTreeTopUp_MaterializesThenCleanHit() { #endregion + #region M: Deferred Dirty-State Propagation + + /*============================================================================================================================ + | TEST: ENSURE LOADED: DIRTY DEFERRED TARGET: RESOLVES AS DIRTY + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Marks a loaded topic's deferred relationship entry as dirty, as 's merge does, via , then resolves it via and confirms the resolved relationship is itself marked dirty, so that a subsequent + /// would persist it. + /// + [Fact] + public async Task EnsureLoaded_DirtyDeferredTarget_ResolvesAsDirty() { + + // The target must not yet be loaded when "Web_1" loads; otherwise Load()'s own resolution (i.e., FillRequestedPayload's + // resolveDeferredTargets) would resolve "Related" immediately, with the default, non-dirty flag, before this test ever gets + // a chance to restamp the entry as dirty + var topic = await _loadingTopicRepository.Load("Root:Web:Web_1"); + var rawTopic = (ITopicBackingAccessor)topic!; + var targetId = rawTopic.Relationships.Deferred.Single(d => d.Key == "Related").TopicId; + + rawTopic.Relationships.Deferred.SetValue("Related", targetId, isDirty: true); + + var target = await _loadingTopicRepository.Load("Root:Web:Web_0:Web_0_0"); + + await _loadingTopicRepository.EnsureLoaded(topic!, TopicPayload.Relationships, cancellationToken: CancellationToken); + + Assert.Contains(target, topic!.Relationships.GetValues("Related")); + Assert.True(topic.Relationships.IsDirty()); + + } + + /*============================================================================================================================ + | TEST: ENSURE LOADED: CLEAN DEFERRED TARGET: RESOLVES AS NOT DIRTY + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Resolves a loaded topic's non-dirty deferred relationship entry via and + /// confirms the resolved relationship is not marked dirty, since it merely reflects data already present in the persistence + /// store, thus the counterpart to . + /// + [Fact] + public async Task EnsureLoaded_CleanDeferredTarget_ResolvesAsNotDirty() { + + // As in EnsureLoaded_DirtyDeferredTarget_ResolvesAsDirty, "Web_1" must load before its target, so "Related" stays deferred + // until EnsureLoaded resolves it, rather than being eagerly resolved by Load()'s own resolution + var topic = await _loadingTopicRepository.Load("Root:Web:Web_1"); + + var target = await _loadingTopicRepository.Load("Root:Web:Web_0:Web_0_0"); + + await _loadingTopicRepository.EnsureLoaded(topic!, TopicPayload.Relationships, cancellationToken: CancellationToken); + + Assert.Contains(target, topic!.Relationships.GetValues("Related")); + Assert.False(topic.Relationships.IsDirty()); + + } + + #endregion + } //Class \ No newline at end of file From 60e0cf93d3473c34a98061d4550bf81e009c7ea6 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Thu, 23 Jul 2026 18:32:06 -0700 Subject: [PATCH 231/337] Added unit test for reciprocal `Clear()` fix Previously, I fixed a preexisting bug where clearing a relationship key via `Clear(key)` would remove the key and its relationships, but fail to remove `IncomingRelationships` (7bfd09e0). This provides a unit test to verify that fix. --- .../TopicRelationshipMultiMapTest.cs | 21 +++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/OnTopic.Tests/TopicRelationshipMultiMapTest.cs b/OnTopic.Tests/TopicRelationshipMultiMapTest.cs index 9b37da3d..bc563d74 100644 --- a/OnTopic.Tests/TopicRelationshipMultiMapTest.cs +++ b/OnTopic.Tests/TopicRelationshipMultiMapTest.cs @@ -451,6 +451,27 @@ public void Clear_ExistingTopics_IsDirty() { } + /*============================================================================================================================ + | TEST: CLEAR: EXISTING TOPICS: REMOVES INCOMING RELATIONSHIP + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Sets a relationship and then clears it by key, and confirms that it is removed from the incoming relationships property + /// of the previously related . + /// + [Fact] + public void Clear_ExistingTopics_RemovesIncomingRelationship() { + + var topic = new Topic("Test", "Page"); + var relationships = new TopicRelationshipMultiMap(topic); + var related = new Topic("Topic", "Page"); + + relationships.SetValue("Related", related); + relationships.Clear("Related"); + + Assert.Null(related.IncomingRelationships.GetValues("Related").FirstOrDefault()); + + } + /*============================================================================================================================ | TEST: CLEAR: NO TOPICS: IS NOT DIRTY \---------------------------------------------------------------------------------------------------------------------------*/ From bc98eb3441f2c06b20a9e35466bb12af7fac894c Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Thu, 23 Jul 2026 18:44:55 -0700 Subject: [PATCH 232/337] Added unit test for `Rollback()` implementation Previously, I migrated the merging of a historical topic version into the graph from `Load(topicId, version)` to `Rollback()` via a new `MergeVersion()` helper (142b9665). This unit tests evaluates that implementation to make sure it works as expected. This takes advantage of the recent updates to the `StubSqlTopicRepository`, such as the new `Load(topicId, version)` overload (30deeb34), `LoadTopicGraph()` intermediary (ff134c0c), and, critically, the `AddHistoricalRelationship()` registration (3e4e0192). --- OnTopic.Tests/TopicRepositoryBaseTest.cs | 59 ++++++++++++++++++++++++ 1 file changed, 59 insertions(+) diff --git a/OnTopic.Tests/TopicRepositoryBaseTest.cs b/OnTopic.Tests/TopicRepositoryBaseTest.cs index afe06710..523dacda 100644 --- a/OnTopic.Tests/TopicRepositoryBaseTest.cs +++ b/OnTopic.Tests/TopicRepositoryBaseTest.cs @@ -5,10 +5,12 @@ \=============================================================================================================================*/ using OnTopic.Collections.Specialized; using OnTopic.Data.Caching; +using OnTopic.Data.Sql; using OnTopic.Metadata; using OnTopic.Repositories; using OnTopic.TestDoubles; using OnTopic.TestDoubles.Metadata; +using OnTopic.Tests.TestDoubles; using Xunit; namespace OnTopic.Tests; @@ -162,6 +164,63 @@ public async Task Rollback_Topic_UpdatesLastModified() { } + /*============================================================================================================================ + | TEST: ROLLBACK: DIVERGENT RELATIONSHIPS: MERGES RECIPROCALLY + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Rolls back a topic whose current Related relationship differs from the historical version being restored: The + /// live topic is currently related to one topic that the historical version doesn't include, and the historical version + /// includes a different topic that the live topic isn't currently related to. Confirms that, after , the live topic's relationship matches the historical version exactly, + /// and that the reciprocal on both the previously and newly related topics are + /// updated to match. + /// + /// + /// Unlike , which used , whose + /// Load(Int32, DateTime) returns the very same live instance being rolled back, short-circuiting 's merge entirely, this uss a , which + /// serves a genuinely detached historical graph via the real, production , with relationship data that can diverge from the current, live state. That divergence is what actually tests the + /// merge. + /// + [Fact] + public async Task Rollback_DivergentRelationships_MergesReciprocally() { + + // Establish a minimal content type graph, required by Save()'s content type validation + var root = new Topic("Root", "Container", null, 1); + var configuration = new Topic("Configuration", "Container", root, 2); + var contentTypes = new ContentTypeDescriptor("ContentTypes", "ContentTypeDescriptor", configuration, 3); + _ = new ContentTypeDescriptor("Page", "ContentTypeDescriptor", contentTypes, 4); + + // Establish topics: A is being rolled back; D is A's current (soon to be stale) relationship; E is A's historical + // relationship, currently unrelated + var topicA = new Topic("A", "Page", root, 100); + var topicD = new Topic("D", "Page", root, 101); + var topicE = new Topic("E", "Page", root, 102); + var version = DateTime.UtcNow.AddDays(-30); + + topicA.Relationships.SetValue("Related", topicD); + topicA.Relationships.MarkClean(); + topicA.VersionHistory.Add(version); + + // Establish repository with divergent historical data: A is historically related to E, not D + var repository = new FakeSqlTopicRepository().AddTopic(100, "A", "Page", null); + + repository.AddHistoricalRelationship(100, "Related", 102); + + // Rollback + await repository.Rollback(topicA, version); + + // A's relationship now matches the historical version + Assert.Contains(topicE, topicA.Relationships.GetValues("Related")); + Assert.DoesNotContain(topicD, topicA.Relationships.GetValues("Related")); + + // Reciprocal relationships were updated on both sides + Assert.DoesNotContain(topicA, topicD.IncomingRelationships.GetValues("Related")); + Assert.Contains(topicA, topicE.IncomingRelationships.GetValues("Related")); + + } + /*============================================================================================================================ | TEST: LOAD: FUTURE DATE: THROWS EXCEPTION \---------------------------------------------------------------------------------------------------------------------------*/ From 1c84037664801fc23369463bff929e8e0aa39b70 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Thu, 23 Jul 2026 18:54:05 -0700 Subject: [PATCH 233/337] Eagerly load immediate children of `root` Previously, in implementation of the lazy-loading feature (#111), I updated the `CachedTopicRepository` to preload only the bare root topic, and then eager load the entire `Configuration` top-tier topic (43ba647f). This refines that default, not fully loading the root topic and it's immediate children, but not their descendants. Anytime the root is being loaded, we expect at least one the immediate children to be requested, and since some of the root topics are `Category` content types that defer to other root topics (for e.g., their navigation) it's more performance to make sure they're all loaded upfront rather than lazy-loading associations on demand. This makes the cache warmup slightly more expensive, but it's still a trivial cost, and should provide a minor improvement to the initial load time by avoiding lazy-loading that we expect will happen. --- OnTopic.Data.Caching/CachedTopicRepository.cs | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/OnTopic.Data.Caching/CachedTopicRepository.cs b/OnTopic.Data.Caching/CachedTopicRepository.cs index 47285330..b734b312 100644 --- a/OnTopic.Data.Caching/CachedTopicRepository.cs +++ b/OnTopic.Data.Caching/CachedTopicRepository.cs @@ -46,10 +46,15 @@ public class CachedTopicRepository : TopicRepositoryDecorator, ITopicLazyLoader public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepository) { /*-------------------------------------------------------------------------------------------------------------------------- - | Seed root topic (without descendants) + | Seed root topic and its immediate children (without grandchildren) + >------------------------------------------------------------------------------------------------------------------------- + | The top-level topics under Root typically represent distinct content buckets (e.g., Web, Configuration) that are commonly + | referenced individually via e.g., relationships used to delegate navigation, so fully loading this shallow tier up front + | avoids the predictable, immediate lazy-load of Root.Children that would otherwise follow. Each child's own Children remain + | deferred, preserving the benefits of lazy loading below this boundary. \-------------------------------------------------------------------------------------------------------------------------*/ var rootTopic = TopicRepository - .Load("Root", referenceTopic: null, isRecursive: false) + .Load("Root", referenceTopic: null, isRecursive: false, payload: TopicPayload.All) .GetAwaiter() .GetResult(); From d2e31a2faf1856993378d516a4edad5725a8e4a3 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 24 Jul 2026 01:48:15 -0700 Subject: [PATCH 234/337] Allow `OnTopicLoaded()` to index ancestors When we load topics outside of the root, we load all ancestors to ensure that they're able to connect to an otherwise sparse graph (2e4b1251, 19688765, de60afb4; c33f4a43). But when we handle an `OnTopicLoaded()` event (7ad38df9c9, 22161b12, f50cd8ba), it only indexes the seed topic (as represented by `OnTopicLoaded()`) and its descendants. This updates it so that it always crawls the tree and indexes ascendants as well. It stops as soon as it hits a topic that's already indexed, so this is cheap assuming the seed is being merged into an existing topic, as will be the case with children. The need for on-demand indexing was introduced with the the lazy-loading implementation (#111). --- OnTopic.Data.Caching/CachedTopicRepository.cs | 22 +++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/OnTopic.Data.Caching/CachedTopicRepository.cs b/OnTopic.Data.Caching/CachedTopicRepository.cs index b734b312..55e3c74f 100644 --- a/OnTopic.Data.Caching/CachedTopicRepository.cs +++ b/OnTopic.Data.Caching/CachedTopicRepository.cs @@ -291,8 +291,8 @@ public virtual async Task EnsureLoaded(Topic topic, TopicPayload payload, Cancel /// Adds the newly loaded topic to the index and clears any entries previously known to be missing, so a topic that was /// missing on an earlier lookup can be found now. This automatically indexes any descendants loaded alongside the topic, /// for cases where the isRecursive parameter was specified on . - /// Ascendants pulled in alongside it are handled separately by , since only one event fires per load, for the requested topic, not each ascendant. + /// Ancestors pulled in via @LoadAscendants sit above the topic, so , + /// which only walks downward, never reaches them; they are indexed by walking up the parent chain instead. /// protected override void OnTopicLoaded(TopicLoadEventArgs args) { @@ -300,9 +300,10 @@ protected override void OnTopicLoaded(TopicLoadEventArgs args) { Contract.Requires(args); base.OnTopicLoaded(args); - // Index the loaded topic and any descendants that came back attached; FindAll() is lazy-safe and naturally returns just - // the topic itself when nothing further is present, so this is correct whether or not the load was recursive lock (_syncLock) { + + // Index the loaded topic and any descendants that came back attached; FindAll() is lazy-safe and naturally returns just + // the topic itself when nothing further is present, so this is correct whether or not the load was recursive foreach (var topic in args.Topic.FindAll()) { if (_topicIdIndex.ContainsKey(topic.Id)) { continue; @@ -311,6 +312,19 @@ protected override void OnTopicLoaded(TopicLoadEventArgs args) { _absentTopicIdIndex.Remove(topic.Id); _absentUniqueKeyIndex.Remove(topic.GetUniqueKey()); } + + // Index any ancestors pulled in via @LoadAscendants, which sit above the requested topic and so are missed by FindAll(). + // Walk up from the parent, stopping at the first already indexed ancestor: The cache is always rooted, so everything + // above an existing ancestor is itself already loaded and indexed. + for (var ancestor = args.Topic.Parent; ancestor is not null; ancestor = ancestor.Parent) { + if (_topicIdIndex.ContainsKey(ancestor.Id)) { + break; + } + IndexTopic(ancestor); + _absentTopicIdIndex.Remove(ancestor.Id); + _absentUniqueKeyIndex.Remove(ancestor.GetUniqueKey()); + } + } } From fa416f38908d73340b8e78a87d5dc33b3dc6271e Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 24 Jul 2026 01:49:02 -0700 Subject: [PATCH 235/337] Remove now-redundant `MergeIntoCache()` MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Outside of the indexing of ascendants, which is now patched where it belongs in `OnTopicLoaded()` d2e31a2f everything in `MergeIntoCache()` is already handled by the `SqlTopicRepository` via `LoadTopicGraph()`—and, moreover, the same would be expected of any underlying `ITopicRepository` implementation, since it's what the `referenceTopic` is meant to allow. This wasn't the case when this was first introduced the `MergeIntoCache()` method as part of the ability to load cache misses (599c5bef), but has subsequently been added by refactors to `LoadTopicGraph()` meant to allow merging divergent `TopicPayload` branches into the existing `referenceTopic` (47769ada, c998de19, 9a7594a6). As a result, this is now redundant. This cleans up the code as the lazy-loading implementation (#111) has matured. --- OnTopic.Data.Caching/CachedTopicRepository.cs | 74 +------------------ OnTopic.Tests/CachedTopicRepositoryTest.cs | 7 +- 2 files changed, 6 insertions(+), 75 deletions(-) diff --git a/OnTopic.Data.Caching/CachedTopicRepository.cs b/OnTopic.Data.Caching/CachedTopicRepository.cs index 55e3c74f..f95f2b1b 100644 --- a/OnTopic.Data.Caching/CachedTopicRepository.cs +++ b/OnTopic.Data.Caching/CachedTopicRepository.cs @@ -149,9 +149,6 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos return null; } - // Merge the returned ancestor chain into the cache, rewiring new topics to existing cache objects - MergeIntoCache(loaded); - // Return the topic from the cache lock (_syncLock) { _topicIdIndex.TryGetValue(topicId, out var result); @@ -228,9 +225,7 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos return null; } - // Merge the returned ancestor chain into the cache, rewiring new topics to existing cache objects - MergeIntoCache(loaded); - + // Return the topic from the cache lock (_syncLock) { _topicKeyIndex.TryGetValue(uniqueKey, out var result); return result; @@ -478,9 +473,8 @@ private void IndexTopic(Topic topic) { /// A single-topic shortfall is topped up via , which converges LoadState in a single batched round-trip. A recursive shortfall, including a whole-tree /// request, performs one deep against the - /// underlying repository—using itself as the reference topic, since it is already resident in, - /// and thus already a valid handle into, the live graph—merges the result into the live graph via , and then looks up any in-graph associations ( itself as the reference into the topic graph, so the underlying + /// load merges the result directly into it. It then looks up any in-graph associations (), so any relationship or reference targets /// that just became resident are connected without a further trip. /// @@ -515,9 +509,6 @@ bool isRecursive if (loaded is not null) { - // Rewire the returned ancestor chain onto the existing cache objects - MergeIntoCache(loaded); - // Opportunistically connect any relationship or reference targets that are now resident in the merged region, regardless // of whether relationships or references were themselves part of the requested payload foreach (var descendant in loaded.FindAll()) { @@ -528,63 +519,4 @@ bool isRecursive } - /*============================================================================================================================ - | METHOD: MERGE INTO CACHE - \---------------------------------------------------------------------------------------------------------------------------*/ - /// - /// Merges a freshly-loaded ancestor chain into the live graph by rewiring each new topic's to - /// the corresponding cache object, then indexing and resolver-stamping any topics that were not previously resident. - /// - /// - /// - /// Called by the and overloads when a requested topic is not present in the flat index and - /// must be fetched from the underlying with @LoadAscendants = true. The load - /// returns a freshly-built graph, including duplicate objects for ancestors already in the cache. - /// This method replaces each duplicate ancestor with the resident cache object, keeps only genuinely new nodes, and - /// integrates them into the live graph. - /// - /// - /// The chain is walked from the leaf toward the root. At the first ancestor already present in _topicById - /// (typically Root), the new node above it is discarded and its child is reparented to the cached object, which - /// attaches it to the existing graph. All new nodes below that boundary are indexed here. - /// - /// - /// The leaf topic returned from the underlying load, already part of an ancestor chain. - private void MergeIntoCache(Topic loaded) { - - // Build the ancestor chain from the leaf up to the root (leaf first) - List chain = []; - for (var node = loaded; node is not null; node = node.Parent) { - chain.Add(node); - } - - // Walk the chain leaf-to-root, rewiring new topics onto the existing cache and indexing them - foreach (var node in chain) { - - // Skip topics that are already present in the cache - lock (_syncLock) { - if (_topicIdIndex.ContainsKey(node.Id)) { - continue; - } - } - - // Rewire to the existing cache parent to prevent duplicate Topic objects in the graph - if (node.Parent is not null) { - lock (_syncLock) { - if (_topicIdIndex.TryGetValue(node.Parent.Id, out var cacheParent) && cacheParent != node.Parent) { - node.Parent = cacheParent; - } - } - } - - // Index the new topic - lock (_syncLock) { - IndexTopic(node); - } - - } - - } - } //Class \ No newline at end of file diff --git a/OnTopic.Tests/CachedTopicRepositoryTest.cs b/OnTopic.Tests/CachedTopicRepositoryTest.cs index d9cf1cc2..f653fdd5 100644 --- a/OnTopic.Tests/CachedTopicRepositoryTest.cs +++ b/OnTopic.Tests/CachedTopicRepositoryTest.cs @@ -106,10 +106,9 @@ public async Task Load_ColdMissTwoLevelsBelowResidentAncestor_AttachesWholeChain /// Simulates the shape produced by , which attaches new topics to an /// existing parent without raising (and thus without indexing them), then calls /// for the leaf and confirms the cache returns - /// the existing instance rather than throwing. Ensures a single-node attachment doesn't crash, with the leaf itself - /// (incorrectly) skipped by MergeIntoCache's dedupe check before its rewire runs, so no collision occurs, while an - /// intermediate, unindexed ancestor ("Web_0") is not skipped: Its rewire collides with the identically keyed topic - /// already attached at that position, throwing . + /// the existing attached instances rather than duplicating them. The merge-aware underlying load reuses the loaded topics + /// via the reference graph, and indexes both the leaf + /// and any previously unindexed intermediate ancestor ("Web_0") by walking up the parent chain. /// [Fact] public async Task Load_AfterAttachedButUnindexedSubtree_ReturnsAttachedInstance() { From f31029441d1de0a2e403c108fc2180d700ed785f Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 24 Jul 2026 01:58:48 -0700 Subject: [PATCH 236/337] Introduced unit tests for indexed ancestors This unit test confirms that the newly introduced indexing of ancestors via `OnTopicLoaded()` works in the `CachedTopicRepository` (d2e31a2f), refining the unit testing for the lazy-loading implementation (#111). --- OnTopic.Tests/CachedTopicRepositoryTest.cs | 39 ++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/OnTopic.Tests/CachedTopicRepositoryTest.cs b/OnTopic.Tests/CachedTopicRepositoryTest.cs index f653fdd5..880896c3 100644 --- a/OnTopic.Tests/CachedTopicRepositoryTest.cs +++ b/OnTopic.Tests/CachedTopicRepositoryTest.cs @@ -99,6 +99,45 @@ public async Task Load_ColdMissTwoLevelsBelowResidentAncestor_AttachesWholeChain } + /*============================================================================================================================ + | TEST: LOAD: COLD MISS TWO LEVELS BELOW RESIDENT ANCESTOR: INDEXES INTERMEDIATE FOR KEY HIT + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Cold-loads a topic ("Web_0_0") two levels below the deepest loaded ancestor ("Web"), pulling the intermediate ("Web_0") + /// into the graph, then requests that intermediate by its unique key and confirms it resolves from the cache's flat key + /// index as a pure hit, with no fall-through to the inner repository. This exercises the ancestor crawl implemented in , which indexes ascendants that the downward-only cannot reach. + /// + [Fact] + public async Task Load_ColdMissTwoLevelsBelowResidentAncestor_IndexesIntermediateForKeyHit() { + + var inner = new FakeSqlTopicRepository() + .AddTopic(1, "Root", "Container", null) + .AddTopic(2, "Web", "Page", 1) + .AddTopic(3, "Web_0", "Page", 2) + .AddTopic(4, "Web_0_0", "Page", 3); + + var cache = new CachedTopicRepository(inner); + await cache.Load("Web"); + + // Cold-load the grandchild, pulling the not-yet-loaded intermediate "Web_0" in as an ancestor + var leaf = await cache.Load(4); + var intermediate = leaf!.Parent; + + Assert.Equal("Web_0", intermediate?.Key); + + // Count loads against the inner repository; an index hit for the intermediate makes no such round-trip + var innerLoads = 0; + inner.TopicLoaded += (_, _) => innerLoads++; + + var resolved = await cache.Load("Root:Web:Web_0"); + + Assert.Same(intermediate, resolved); + Assert.Equal(0, innerLoads); + + } + /*============================================================================================================================ | TEST: LOAD: AFTER ATTACHED-BUT-UNINDEXED SUBTREE: RETURNS ATTACHED INSTANCE \---------------------------------------------------------------------------------------------------------------------------*/ From 8d0af7d590d34b81ba236d06165a989cb2564b95 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 24 Jul 2026 15:09:45 -0700 Subject: [PATCH 237/337] Update unit test to match updated seed Yesterday, I updated the `CachedTopicService` to fully seed the immediate children of the root topic, in addition to the root topic itself (1c840376). When I did this, however, I failed to update the unit test evaluating it to match that revised expectation. This fixes that. --- OnTopic.Tests/LazyLoadingTopicRepositoryTest.cs | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/OnTopic.Tests/LazyLoadingTopicRepositoryTest.cs b/OnTopic.Tests/LazyLoadingTopicRepositoryTest.cs index 68616f0b..aeaf022e 100644 --- a/OnTopic.Tests/LazyLoadingTopicRepositoryTest.cs +++ b/OnTopic.Tests/LazyLoadingTopicRepositoryTest.cs @@ -715,8 +715,9 @@ public async Task Load_RecursiveTopUp_InGraphCoreConnectsMergedRegion() { | TEST: LOAD: WHOLE TREE TOP UP: MATERIALIZES THEN CLEAN HIT \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Seeds the cache with the default, shallow Root (, non-recursive), then requests - /// the whole tree recursively via the topicId < 0 branch, and confirms every descendant is materialized and Root seed established by the constructor + /// (Root plus its immediate children, per its eager top-tier load, but not their descendants), then requests the + /// whole tree recursively via the topicId < 0 branch, and confirms every descendant is materialized and , and that a third, identical call is a genuine, converged hit against the same instance with /// no further fetches, thus exercising the 's own lazy Root boundary, /// as per 's documented lazy defaults, alongside EnsureLoaded's whole-tree @@ -731,7 +732,7 @@ public async Task Load_WholeTreeTopUp_MaterializesThenCleanHit() { var seed = await cache.Load(-1, null, false, TopicPayload.None); - Assert.False(((ITopicLazyLoadable)seed!).IsLoaded(TopicPayload.Children)); + Assert.True(((ITopicLazyLoadable)seed!).IsLoaded(TopicPayload.Children)); var loaded = await cache.Load(-1, seed, true, TopicPayload.All); From b511349289ca7b7675c5a0bc879dbedf00eb510e Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Fri, 24 Jul 2026 15:46:43 -0700 Subject: [PATCH 238/337] Support convergence in lazy-loading stub MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit When I updated `SqlTopicRepository` to support updating existing topics to fulfill mismatched `TopicPayload` requests via `ConvergeLoadState()` (47769ada, c998de19), I failed to apply a similar update to the `StubLazyLoadingTopicRepository` test double (aa2c4764). When fixing the unit tests to expect the `Children` or the root topic to be found (8d0af7d5), this exposed the issue with the `Configuration` not being loaded since it was already found in the topic graph—despite the `Load()` request expecting `TopicPayload.All` and `isRecursive`, which were not satisfied for it. This fixes that gap, thus fixing the unit tests, and contributing further to the testing ot the lazy-loading infrastructure (#111). --- .../StubLazyLoadingTopicRepository.cs | 41 ++++++++++++------- 1 file changed, 26 insertions(+), 15 deletions(-) diff --git a/OnTopic.TestDoubles/LazyLoading/StubLazyLoadingTopicRepository.cs b/OnTopic.TestDoubles/LazyLoading/StubLazyLoadingTopicRepository.cs index ab45b757..8d4766db 100644 --- a/OnTopic.TestDoubles/LazyLoading/StubLazyLoadingTopicRepository.cs +++ b/OnTopic.TestDoubles/LazyLoading/StubLazyLoadingTopicRepository.cs @@ -316,8 +316,9 @@ await FillRequestedPayload( /// fetched from the record store one level at a time, unless is set, in which case /// rides along so every descendant, not merely the immediate children, are /// filled. A child already present in (e.g., attached while building an ancestor chain for a deeper - /// call) is reused rather than rebuilt, to avoid colliding with - /// the existing instance already attached to the graph. + /// call, or eagerly preloaded) is reused rather than rebuilt, to + /// avoid colliding with the existing instance already attached to the graph, but is still offered the requested payload so + /// a resident child converges to the requested scope instead of being silently skipped. /// /// The topic whose requested payload should be filled. /// The requested flags. @@ -370,7 +371,12 @@ CancellationToken cancellationToken payload = ((ITopicLazyLoadable)topic).FilterPayload(payload); - if (payload is TopicPayload.None) { + // An isRecursive request for Children must still descend into an already-Loaded Children collection, since that only means + // this topic's immediate children are resident, not that their own descendants have converged to the requested scope; + // FilterPayload has no visibility into descendants, so it can't account for this on its own + var descendIntoChildren = isRecursive && requestedPayload.HasFlag(TopicPayload.Children); + + if (payload is TopicPayload.None && !descendIntoChildren) { return; } @@ -383,35 +389,40 @@ CancellationToken cancellationToken | Unlike ExtendedAttributes, Children never needs a record of its own to fill: It is resolved purely by scanning the store | for records whose ParentId matches, including Root, whose top-level records are stored with a null ParentId \-------------------------------------------------------------------------------------------------------------------------*/ - if (payload.HasFlag(TopicPayload.Children)) { + if (payload.HasFlag(TopicPayload.Children) || descendIntoChildren) { // Loop through each child record and build the topic from the topic store foreach (var childRecord in _store.Values.Where(r => (r.ParentId?? _root.Id) == topic.Id).OrderBy(r => r.Id)) { - // Build the child record, assuming it hasn't already been served - if (_served.ContainsKey(childRecord.Id)) { - continue; - } - var child = BuildTopic(childRecord, topic); + // Reuse the child if it's already been served (e.g., attached while building an ancestor chain, or eagerly preloaded), + // rather than rebuilding it and colliding with the existing instance already attached to the graph + var isNewlyBuilt = !_served.TryGetValue(childRecord.Id, out var child); + child ??= BuildTopic(childRecord, topic); // Load the rest of the requested payload for the child, mirroring how a Children fetch also pulls in whatever else was // requested (e.g., ExtendedAttributes, VersionHistory) for the whole scope, while relationships and references always // ride along for free. When isRecursive, Children rides along too, so the fill descends into the entire subtree rather // than stopping at one level. This uses requestedPayload, not the filtered payload, since a property that is already - // Loaded on a topic doesn't imply it's also already loaded on the child + // Loaded on a topic doesn't imply it's also already loaded on the child. This applies whether the child was just built + // or already served, so an existing child (e.g., eagerly preloaded) still converges to the requested scope var childPayload = (isRecursive? requestedPayload : requestedPayload & ~TopicPayload.Children) | TopicPayload.Relationships | TopicPayload.References; await FillRequestedPayload(child, childPayload, resolveDeferredTargets: false, isRecursive, cancellationToken).ConfigureAwait(false); - // Fire the TopicLoaded event - OnTopicLoaded(new(child, isRecursive)); + // Fire the TopicLoaded event, if newly built; an already served child was already announced when it was first built + if (isNewlyBuilt) { + OnTopicLoaded(new(child, isRecursive)); + } } - // Mark the children as fetched and loaded - RecordFetch(topic.Id, TopicPayload.Children); - ((ITopicLazyLoadable)topic).SetLoadState(TopicPayload.Children, LoadState.Loaded); + // Mark the children as fetched and loaded, if not already done; an already-Loaded Children collection, revisited only to + // descend for an isRecursive request, needs no re-fetch or re-stamp of its own + if (payload.HasFlag(TopicPayload.Children)) { + RecordFetch(topic.Id, TopicPayload.Children); + ((ITopicLazyLoadable)topic).SetLoadState(TopicPayload.Children, LoadState.Loaded); + } } From 5ab6d721f50ef9ff173be340ab934e21546e29b8 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sat, 25 Jul 2026 20:13:50 -0700 Subject: [PATCH 239/337] Introduced `ChildTopicCollection` This will provide a specialized collection for `Topic.Children`. Currently, this doesn't really do anything, but it'll be extended in subsequent commits. This is a core deliverable for the collection integration (#119) of the lazy-loading feature (#111). --- OnTopic/Collections/ChildTopicCollection.cs | 38 +++++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 OnTopic/Collections/ChildTopicCollection.cs diff --git a/OnTopic/Collections/ChildTopicCollection.cs b/OnTopic/Collections/ChildTopicCollection.cs new file mode 100644 index 00000000..57118e7a --- /dev/null +++ b/OnTopic/Collections/ChildTopicCollection.cs @@ -0,0 +1,38 @@ +/*============================================================================================================================== +| Author Ignia, LLC +| Client Ignia, LLC +| Project Topics Library +\=============================================================================================================================*/ +using OnTopic.Repositories; + +namespace OnTopic.Collections; + +/*============================================================================================================================== +| CLASS: CHILD TOPIC COLLECTION +\-----------------------------------------------------------------------------------------------------------------------------*/ +/// +/// Provides a collection of objects representing the immediate children of a . +/// +/// +/// The is intended exclusively for providing access to children via the property. For this reason, the constructor is marked as internal. +/// +public class ChildTopicCollection : KeyedTopicCollection { + + /*============================================================================================================================ + | PRIVATE VARIABLES + \---------------------------------------------------------------------------------------------------------------------------*/ + private readonly Topic _parent; + + /*============================================================================================================================ + | CONSTRUCTOR + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Initializes a new instance of the class. + /// + /// A reference to the topic that the current child collection is bound to. + internal ChildTopicCollection(Topic parent) { + _parent = parent; + } + +} //Class \ No newline at end of file From ca5ffe66e05cd2ad4813583b6078a3170f493b95 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sat, 25 Jul 2026 20:14:27 -0700 Subject: [PATCH 240/337] Implement `ChildTopicCollection` This implements the new `ChildTopicCollection` (5ab6d721) as the base type for `Topic.Children`, as it was intended. This is a core deliverable for the collection integration (#119) of the lazy-loading feature (#111). --- OnTopic/Repositories/ITopicBackingAccessor.cs | 4 ++-- OnTopic/Topic.cs | 11 ++++++++--- 2 files changed, 10 insertions(+), 5 deletions(-) diff --git a/OnTopic/Repositories/ITopicBackingAccessor.cs b/OnTopic/Repositories/ITopicBackingAccessor.cs index 8e29c923..51f6b362 100644 --- a/OnTopic/Repositories/ITopicBackingAccessor.cs +++ b/OnTopic/Repositories/ITopicBackingAccessor.cs @@ -32,13 +32,13 @@ public interface ITopicBackingAccessor { | PROPERTY: CHILDREN \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Returns the raw backing field, bypassing the autoloading getter. + /// Returns the raw backing field, bypassing the autoloading getter. /// /// /// This is to be applied as explicit interface implementations; callers must cast to to /// access this member. /// - KeyedTopicCollection Children { get; } + ChildTopicCollection Children { get; } /*============================================================================================================================ | PROPERTY: RELATIONSHIPS diff --git a/OnTopic/Topic.cs b/OnTopic/Topic.cs index 8d4a9a4b..889de18a 100644 --- a/OnTopic/Topic.cs +++ b/OnTopic/Topic.cs @@ -28,7 +28,7 @@ public class Topic: ITrackDirtyKeys, ITopicLazyLoadable { private string _contentType; private string? _originalKey; private Topic? _parent; - private readonly KeyedTopicCollection _children = []; + private readonly ChildTopicCollection _children; private readonly TopicRelationshipMultiMap _relationships; private readonly TopicReferenceCollection _references; private readonly VersionHistoryCollection _versionHistory = []; @@ -58,6 +58,11 @@ public class Topic: ITrackDirtyKeys, ITopicLazyLoadable { /// A strongly-typed instance of the class based on the target content type. public Topic(string key, string contentType, Topic? parent = null, int id = -1) { + /*-------------------------------------------------------------------------------------------------------------------------- + | Set children first, since setting Id or Parent below may fire registry hooks that read this topic's children + \-------------------------------------------------------------------------------------------------------------------------*/ + _children = new(this); + /*-------------------------------------------------------------------------------------------------------------------------- | Set collections \-------------------------------------------------------------------------------------------------------------------------*/ @@ -160,7 +165,7 @@ public Topic? Parent { /// /// The children of the current . /// - public KeyedTopicCollection Children { + public ChildTopicCollection Children { get { if (_children.LoadState is LoadState.NotLoaded) { ((ITopicLazyLoadable)this).EnsureLoaded(TopicPayload.Children).GetAwaiter().GetResult(); @@ -451,7 +456,7 @@ public DateTime LastModified { \---------------------------------------------------------------------------------------------------------------------------*/ /// - KeyedTopicCollection ITopicBackingAccessor.Children => _children; + ChildTopicCollection ITopicBackingAccessor.Children => _children; /// TopicRelationshipMultiMap ITopicBackingAccessor.Relationships => _relationships; From b30ab9ef63b0bbaca7bb5ecbec0eac6ec55b7c06 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sat, 25 Jul 2026 20:19:27 -0700 Subject: [PATCH 241/337] Moved `LoadState` to `ChildTopicCollection` The `LoadState` isn't really relevant to the `KeyedTopicCollection`, and other collections all handle this at their implementation level, not in their underlying collections. (See e.g., `AttributeCollection`, `RelationshipTopicMultiMap`, and `ReferenceTopicCollection`). This resulted in the `LoadState` being accessible to other consumers of the generic `KeyedTopicCollection`, even though they had no need for it. With the `ChildTopicCollection` in place (5ab6d721, ca5ffe66) we can now safely move this up one level so it's handled where it's needed. This is a core deliverable for the collection integration (#119) of the lazy-loading feature (#111). --- OnTopic/Collections/ChildTopicCollection.cs | 25 +++++++++++++++++++ .../Collections/KeyedTopicCollection{T}.cs | 16 ------------ 2 files changed, 25 insertions(+), 16 deletions(-) diff --git a/OnTopic/Collections/ChildTopicCollection.cs b/OnTopic/Collections/ChildTopicCollection.cs index 57118e7a..5a1ae1c4 100644 --- a/OnTopic/Collections/ChildTopicCollection.cs +++ b/OnTopic/Collections/ChildTopicCollection.cs @@ -35,4 +35,29 @@ internal ChildTopicCollection(Topic parent) { _parent = parent; } + /*============================================================================================================================ + | PROPERTY: LOAD STATE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Indicates whether the collection has been populated from the underlying , + /// allowing callers to distinguish data that is present and authoritative from data that must still be fetched. + /// + /// + /// + /// Defaults to , reflecting that a newly constructed, in-memory collection has nothing + /// deferred. When a topic is loaded shallowly from the persistence store, the repository conditionally sets this to to indicate that the immediate children have not yet been fetched. The persistence store + /// may optionally provide an indicator of the count without returning the full data, thus allowing this to be set to if, in fact, there are no relevant topics. + /// + /// + /// This setter exists for implementations populating or converging load state + /// during or . Setting + /// while children remain unfetched masks the deferral from subsequent readers; setting + /// on already-resident children induces a spurious synchronous load on next access. + /// + /// + public LoadState LoadState { get; set; } = LoadState.Loaded; + } //Class \ No newline at end of file diff --git a/OnTopic/Collections/KeyedTopicCollection{T}.cs b/OnTopic/Collections/KeyedTopicCollection{T}.cs index 26e49b55..5dae6309 100644 --- a/OnTopic/Collections/KeyedTopicCollection{T}.cs +++ b/OnTopic/Collections/KeyedTopicCollection{T}.cs @@ -30,22 +30,6 @@ public KeyedTopicCollection(IEnumerable? topics = null) : base(StringComparer } } - /*============================================================================================================================ - | PROPERTY: LOAD STATE - \---------------------------------------------------------------------------------------------------------------------------*/ - /// - /// Indicates whether the collection has been populated from the underlying , - /// allowing callers to distinguish data that is present and authoritative from data that must still be fetched. - /// - /// - /// Defaults to , reflecting that a newly constructed, in-memory collection has nothing - /// deferred. When a topic is loaded shallowly from the persistence store, the repository conditionally sets this to - /// to indicate that the immediate children have not yet been fetched. The persistence - /// store may optionally provide an indicator of the count without returning the full data, thus allowing this to be set to - /// if, in fact, there are no relevant topics. - /// - public LoadState LoadState { get; set; } = LoadState.Loaded; - /*============================================================================================================================ | METHOD: GET VALUE \---------------------------------------------------------------------------------------------------------------------------*/ From 0a30ecd7e993bae7640050fcc80422ed8b8964eb Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sun, 26 Jul 2026 16:18:40 -0700 Subject: [PATCH 242/337] Ensured proper sort order for `GetTopicUpdates` The `GetTopics` stored procedure already sorts by `RangeLeft` which, per the mechanics of a nested set, ensures that ascendants of topics are delivered prior to their descendants, which allows them to rely on parents already being in the topic graph as they're processed. This wasn't the case for the `GetTopicUpdates` stored procedure, however, even though it's capable of delivering new topics. While this is a long-standing bug, this is being fixed now as part of the introduction of a `TopicIndex` cache (#116), which will include improvements to how `Refresh()` merges into the topic graph via that index. --- OnTopic.Data.Sql.Database/Stored Procedures/GetTopicUpdates.sql | 1 + 1 file changed, 1 insertion(+) diff --git a/OnTopic.Data.Sql.Database/Stored Procedures/GetTopicUpdates.sql b/OnTopic.Data.Sql.Database/Stored Procedures/GetTopicUpdates.sql index b6f1c89a..a767c41f 100644 --- a/OnTopic.Data.Sql.Database/Stored Procedures/GetTopicUpdates.sql +++ b/OnTopic.Data.Sql.Database/Stored Procedures/GetTopicUpdates.sql @@ -20,6 +20,7 @@ SELECT TopicID, HasExtendedAttributes = NULL FROM Topics WHERE LastModified > @Since +ORDER BY RangeLeft -------------------------------------------------------------------------------------------------------------------------------- -- SELECT TOPIC ATTRIBUTES From 94b763c067ed2efa2c25ac50fa07335c2a0f6699 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sun, 26 Jul 2026 16:21:11 -0700 Subject: [PATCH 243/337] Fixed minor spelling errors in comments --- OnTopic/Mapping/Annotations/AssociationTypes.cs | 2 +- OnTopic/Querying/TopicExtensions.cs | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/OnTopic/Mapping/Annotations/AssociationTypes.cs b/OnTopic/Mapping/Annotations/AssociationTypes.cs index ae355ddc..3d888d59 100644 --- a/OnTopic/Mapping/Annotations/AssociationTypes.cs +++ b/OnTopic/Mapping/Annotations/AssociationTypes.cs @@ -80,7 +80,7 @@ public enum AssociationTypes { /// cref="AttributeKeyAttribute.Key"/>. /// /// - /// This allows mapping of custom collection, such as . + /// This allows mapping of custom collections, such as . /// MappedCollections = 1 << 4, diff --git a/OnTopic/Querying/TopicExtensions.cs b/OnTopic/Querying/TopicExtensions.cs index 488bad18..0bbea061 100644 --- a/OnTopic/Querying/TopicExtensions.cs +++ b/OnTopic/Querying/TopicExtensions.cs @@ -122,7 +122,7 @@ public static class TopicExtensions { /// /// The instance of the to operate against; populated automatically by .NET. /// A collection of topics descending from the current topic. - public static ReadOnlyTopicCollection FindAll(this Topic topic) => topic.FindAll(t => true); + public static ReadOnlyTopicCollection FindAll(this Topic topic) => topic.FindAll(_ => true); /// /// Retrieves a collection of topics based on a supplied function. @@ -249,7 +249,7 @@ public static ReadOnlyTopicCollection FindAllByAttribute(this Topic topic, strin /// /// This will trigger synchronous lazy-loading calls to any topics in the chain whose children aren't yet loaded. That can /// make initial calls to this unexpectedly expensive on a lazy-loaded topic tree, resulting in multiple calls to the - /// underlying persistance store. + /// underlying persistence store. /// /// The instance of the to operate against; populated automatically by .NET. /// The of the to return. From ffb77d9363123a65cde3f17f89bd4cd80de5204d Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sun, 26 Jul 2026 17:20:12 -0700 Subject: [PATCH 244/337] Convert `TopicIndex` to `ConcurrentDictionary<>` While concurrency was potentially an issue previously, it is certainly an issue with the combination of a) lazy loading (#111) and b) the forthcoming `TopicIndex` caching (#116), where a lot more mutations will be occurring of a shared `TopicIndex`. In addition, this includes throwing an `ArgumentException` on a duplicate key. This was already backed into the `Dictionary<>`, but with the migration to `ConcurrentDictionary<>`, the `TryAdd()` would hide this error, silently skipping it. --- OnTopic.Data.Sql/SqlDataReaderExtensions.cs | 2 +- OnTopic/Collections/Specialized/TopicIndex.cs | 18 +++++++++++++++--- 2 files changed, 16 insertions(+), 4 deletions(-) diff --git a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs index 71fce0df..e9d50b7b 100644 --- a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs +++ b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs @@ -226,7 +226,7 @@ private static Topic AddTopic(this IDataReader reader, TopicIndex topics, bool? \-------------------------------------------------------------------------------------------------------------------------*/ if (!topics.TryGetValue(topicId, out var current)) { current = TopicFactory.Create(key, contentType, topicId); - topics.Add(current.Id, current); + topics.TryAdd(current.Id, current); // Default to NotLoaded; a corresponding row in the version history dataset, if any, promotes this to Loaded ((ITopicBackingAccessor)current).VersionHistory.LoadState = LoadState.NotLoaded; } diff --git a/OnTopic/Collections/Specialized/TopicIndex.cs b/OnTopic/Collections/Specialized/TopicIndex.cs index 34e1bb9b..e7785872 100644 --- a/OnTopic/Collections/Specialized/TopicIndex.cs +++ b/OnTopic/Collections/Specialized/TopicIndex.cs @@ -3,6 +3,8 @@ | Client Ignia, LLC | Project Topics Library \=============================================================================================================================*/ +using System.Collections.Concurrent; +using OnTopic.Repositories; namespace OnTopic.Collections.Specialized; @@ -12,7 +14,13 @@ namespace OnTopic.Collections.Specialized; /// /// Represents a collection of objects indexed by . /// -public class TopicIndex : Dictionary { +/// +/// Backed by , allowing an implementation to +/// share a single topic graph across concurrent callers, and most notably when caching is involved, since lazy loading +/// mutates the graph as callers read properties that aren't yet loaded. The index must tolerate concurrent reads and writes +/// regardless of which implementation is being used. +/// +public class TopicIndex : ConcurrentDictionary { /*============================================================================================================================ | CONSTRUCTOR @@ -24,7 +32,9 @@ public class TopicIndex : Dictionary { /// /// Unsaved instances () are skipped, since their is a /// placeholder shared by every other unsaved topic, not a real identity, and so isn't a genuine collision. Any other - /// colliding reflects corrupt data and continues to throw. + /// colliding reflects corrupt data and continues to throw; e.g., a bulk seed of corrupt data should + /// fail clearly. This is deliberately stricter than the tolerate semantics of the live index's attach and detach methods, + /// which must not throw in the middle of an operation. /// public TopicIndex(IEnumerable? topics = null) { if (topics is not null) { @@ -32,7 +42,9 @@ public TopicIndex(IEnumerable? topics = null) { if (topic.IsNew) { continue; } - Add(topic.Id, topic); + if (!TryAdd(topic.Id, topic)) { + throw new ArgumentException($"An item with the same key has already been added. Key: {topic.Id}", nameof(topics)); + } } } } From a15ae85f5163bbf2603b2cc2380fe25c16893662 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sun, 26 Jul 2026 18:06:47 -0700 Subject: [PATCH 245/337] Introduced the `TopicIndexRegistry` This is the core component of the `TopicIndex` caching project (#116), and as it not only established the Conditional Weak Table (CWT) for the cache, but also provides a series of methods that `Topic` will be updated to maintain when topics are added or removed from a topic graph, or when a new topic is saved and thus eligible to be indexed in the graph. --- .../Specialized/TopicIndexRegistry.cs | 162 ++++++++++++++++++ 1 file changed, 162 insertions(+) create mode 100644 OnTopic/Collections/Specialized/TopicIndexRegistry.cs diff --git a/OnTopic/Collections/Specialized/TopicIndexRegistry.cs b/OnTopic/Collections/Specialized/TopicIndexRegistry.cs new file mode 100644 index 00000000..c8f44560 --- /dev/null +++ b/OnTopic/Collections/Specialized/TopicIndexRegistry.cs @@ -0,0 +1,162 @@ +/*============================================================================================================================== +| Author Ignia, LLC +| Client Ignia, LLC +| Project Topics Library +\=============================================================================================================================*/ +using System.Runtime.CompilerServices; +using OnTopic.Querying; +using OnTopic.Repositories; + +namespace OnTopic.Collections.Specialized; + +/*============================================================================================================================== +| CLASS: TOPIC INDEX REGISTRY +\-----------------------------------------------------------------------------------------------------------------------------*/ +/// +/// Maintains a single, live, incrementally maintained per topic graph, keyed by root . +/// +/// +/// +/// The graph itself remains the source of truth; an entry is a disposable derivation of it, kept in sync incrementally as +/// topics are attached, detached, or assigned IDs, but recoverable at any time by discarding it and walking the graph again +/// via . Keying by root instance also provides isolation +/// for tests, as distinct graphs produce disjoint entries, with nothing to reset, and weak keys mean a released graph still +/// releases its index without any explicit lifetime management. +/// +/// +/// Callers never write to this registry directly; the public surface is the read-only accessor. The registry itself is maintained exclusively by 's attach and detach hooks and the 's setter, which call the internal +/// members below as topics are attached, detached, or assigned a persisted identifier. +/// +/// +internal static class TopicIndexRegistry { + + /*============================================================================================================================ + | PRIVATE FIELDS + \---------------------------------------------------------------------------------------------------------------------------*/ + private static readonly ConditionalWeakTable _indexes = new(); + + /*============================================================================================================================ + | METHOD: GET OR BUILD + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Returns the live for the graph rooted at , building and storing + /// it on first access. + /// + /// + /// Seeded by walking the 's full tree via , which + /// never triggers a lazy load and includes topics under NotLoaded . + /// must genuinely be a root (i.e., Parent is null); callers reach this exclusively via + /// , which derives it from any node. + /// + /// The root of the graph whose live index should be returned. + internal static TopicIndex GetOrBuild(Topic rootTopic) => _indexes.GetValue(rootTopic, root => new(root.FindAll())); + + /*============================================================================================================================ + | METHOD: ON ATTACHED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Indexes and its physical subtree into the live index of 's root, + /// assuming that index has been materialized. + /// + /// + /// Called from , after the base insertion, with being the collection's owner rather than .Parent, as the latter is not yet set + /// when the insertion fires. 's own registry entry is removed first, in case it was itself a root + /// with a materialized index before this attach (e.g., loaded standalone, then merged under 's + /// graph): Attaching it here means it's no longer a root, so that entry is now stale, and + /// would otherwise hand it back unchanged, rather than rebuilding, if were later detached and + /// became a root again. topics are skipped, since their placeholder is not + /// a genuine identity. + /// + /// The that owns the collection was inserted into. + /// The that was attached. + internal static void OnAttached(Topic parent, Topic child) { + + // The child may itself have been a root with a stale materialized index; always drop that entry + _indexes.Remove(child); + + // Skip unless the parent's root already has a materialized index to maintain + if (!_indexes.TryGetValue(parent.GetRootTopic(), out var index)) { + return; + } + + // Index the child and its physical subtree; tolerate-resident, since a duplicate id here reflects a benign re-attach + foreach (var topic in child.FindAll()) { + if (topic.IsNew) { + continue; + } + index.TryAdd(topic.Id, topic); + } + + } + + /*============================================================================================================================ + | METHOD: ON DETACHED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Removes and its physical subtree from the live index of 's root, if + /// that index has been materialized. + /// + /// + /// Called from , before the base removal, with being the collection's owner. 's subtree must be computed while it is still reachable, hence + /// being place before the base is removed. topics are skipped, since they'll never had been + /// indexed originally, matching . + /// + /// + /// The that owns the collection is being removed from. + /// + /// The being detached. + internal static void OnDetached(Topic parent, Topic child) { + + // Skip unless the parent's root already has a materialized index to maintain + if (!_indexes.TryGetValue(parent.GetRootTopic(), out var index)) { + return; + } + + // Remove the child and its physical subtree + foreach (var topic in child.FindAll()) { + if (topic.IsNew) { + continue; + } + index.TryRemove(topic.Id, out _); + } + + } + + /*============================================================================================================================ + | METHOD: ON ID ASSIGNED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Indexes into the live index of its own root, if that index has been materialized. + /// + /// + /// Called from 's setter after a persisted identifier is assigned (i.e., following ). The setter's guard permits re-setting the same value, so this may fire + /// repeatedly for a given topic; TryAdd covers that without an assumption that it fires once. + /// + /// The that was just assigned a persisted . + internal static void OnIdAssigned(Topic topic) { + if (_indexes.TryGetValue(topic.GetRootTopic(), out var index)) { + index.TryAdd(topic.Id, topic); + } + } + + /*============================================================================================================================ + | METHOD: INVALIDATE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Discards the materialized live index for the graph rooted at , if any; the next rebuilds it from scratch. + /// + /// + /// Called from : A bulk detach, where per-item bookkeeping via isn't worth the cost, relative to just rebuilding the index in this rare scenario. + /// + /// The root of the graph whose live index should be discarded. + internal static void Invalidate(Topic rootTopic) => _indexes.Remove(rootTopic); + +} //Class \ No newline at end of file From 273beeb27bb64ffaaaf8608a448ddde1fa6f751a Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sun, 26 Jul 2026 18:23:02 -0700 Subject: [PATCH 246/337] Wire-up `TopicIndexRegistry` "event handlers" This calls the four event-handler-style methods on the new `TopicIndexRegistry` (a15ae85f), so the index is automatically built and maintained in response to topics being added or removed or saved. This contributes to the `TopicIndex` caching (#116). --- OnTopic/Collections/ChildTopicCollection.cs | 60 ++++++++++++++++--- .../Collections/KeyedTopicCollection{T}.cs | 2 +- OnTopic/Topic.cs | 1 + 3 files changed, 55 insertions(+), 8 deletions(-) diff --git a/OnTopic/Collections/ChildTopicCollection.cs b/OnTopic/Collections/ChildTopicCollection.cs index 5a1ae1c4..aa5409ae 100644 --- a/OnTopic/Collections/ChildTopicCollection.cs +++ b/OnTopic/Collections/ChildTopicCollection.cs @@ -3,6 +3,8 @@ | Client Ignia, LLC | Project Topics Library \=============================================================================================================================*/ +using OnTopic.Collections.Specialized; +using OnTopic.Querying; using OnTopic.Repositories; namespace OnTopic.Collections; @@ -39,8 +41,8 @@ internal ChildTopicCollection(Topic parent) { | PROPERTY: LOAD STATE \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Indicates whether the collection has been populated from the underlying , - /// allowing callers to distinguish data that is present and authoritative from data that must still be fetched. + /// Indicates whether the collection has been populated from the underlying , allowing + /// callers to distinguish data that is present and authoritative from data that must still be fetched. /// /// /// @@ -51,13 +53,57 @@ internal ChildTopicCollection(Topic parent) { /// cref="LoadState.Loaded"/> if, in fact, there are no relevant topics. /// /// - /// This setter exists for implementations populating or converging load state - /// during or . Setting - /// while children remain unfetched masks the deferral from subsequent readers; setting - /// on already-resident children induces a spurious synchronous load on next access. + /// This setter exists for implementations populating or converging load state during or . + /// Setting while children remain unfetched masks the deferral from subsequent readers; + /// setting on already-resident children induces a spurious synchronous load on + /// next access. /// /// public LoadState LoadState { get; set; } = LoadState.Loaded; + /*============================================================================================================================ + | OVERRIDE: INSERT ITEM + \---------------------------------------------------------------------------------------------------------------------------*/ + /// Fires any time a is added to the collection. + /// + /// Extends the base insertion with , so that the newly attached and its subtree are reflected in the live of the topic's root, assuming that index has + /// been materialized. + /// + /// The zero-based index at which should be inserted. + /// The instance to insert. + protected sealed override void InsertItem(int index, Topic item) { + base.InsertItem(index, item); + TopicIndexRegistry.OnAttached(_parent, item); + } + + /*============================================================================================================================ + | OVERRIDE: REMOVE ITEM + \---------------------------------------------------------------------------------------------------------------------------*/ + /// Fires any time a is removed from the collection. + /// + /// Extends the base removal with , computed from the item + /// before the base removal executes, since the detach bookkeeping needs the subtree while it's still reachable. + /// + /// The zero-based index of the to remove. + protected sealed override void RemoveItem(int index) { + var item = this[index]; + TopicIndexRegistry.OnDetached(_parent, item); + base.RemoveItem(index); + } + + /*============================================================================================================================ + | OVERRIDE: CLEAR ITEMS + \---------------------------------------------------------------------------------------------------------------------------*/ + /// Fires when the collection is cleared. + /// + /// Extends the base clear with : a bulk detach, where per-item + /// bookkeeping via isn't worth it. + /// + protected sealed override void ClearItems() { + TopicIndexRegistry.Invalidate(_parent.GetRootTopic()); + base.ClearItems(); + } + } //Class \ No newline at end of file diff --git a/OnTopic/Collections/KeyedTopicCollection{T}.cs b/OnTopic/Collections/KeyedTopicCollection{T}.cs index 5dae6309..d62140bf 100644 --- a/OnTopic/Collections/KeyedTopicCollection{T}.cs +++ b/OnTopic/Collections/KeyedTopicCollection{T}.cs @@ -72,7 +72,7 @@ public KeyedTopicCollection(IEnumerable? topics = null) : base(StringComparer /// A {typeof(T).Name} with the Key '{item.Key}' already exists. The UniqueKey of the existing {typeof(T).Name} is /// '{GetUniqueKey()}'; the new item's is '{item.GetUniqueKey()}'. /// - protected override sealed void InsertItem(int index, T item) { + protected override void InsertItem(int index, T item) { /*-------------------------------------------------------------------------------------------------------------------------- | Validate parameters diff --git a/OnTopic/Topic.cs b/OnTopic/Topic.cs index 889de18a..5a69478a 100644 --- a/OnTopic/Topic.cs +++ b/OnTopic/Topic.cs @@ -122,6 +122,7 @@ public int Id { throw new InvalidOperationException($"The value of this topic has already been set to {field}; it cannot be changed."); } field = value; + TopicIndexRegistry.OnIdAssigned(this); } } = -1; From a18d8d59ff6c30420cf5d576e1d86d4d14f799ad Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sun, 26 Jul 2026 18:37:23 -0700 Subject: [PATCH 247/337] Introduced `GetLiveTopicIndex()` method to `Topic` This complements the existing `GetTopicIndex()`, instead returning a cached (but actively maintained) version of the `TopicIndex` (a15ae85f) so that it doesn't need to be recomputed on each request, as was frequently the case previously. This fulfills the core promise of the `TopicIndex` cache (#116). Note that I don't love the term "live" here, but "cached" also implies a static snapshot, which is confusing. I may revisit this later, before deployed v6.0.0. --- OnTopic/Querying/TopicExtensions.cs | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/OnTopic/Querying/TopicExtensions.cs b/OnTopic/Querying/TopicExtensions.cs index 0bbea061..7d4a75f8 100644 --- a/OnTopic/Querying/TopicExtensions.cs +++ b/OnTopic/Querying/TopicExtensions.cs @@ -224,12 +224,30 @@ public static ReadOnlyTopicCollection FindAllByAttribute(this Topic topic, strin /// /// /// This only loads topics from the in-memory topic graph. Any topics that aren't yet loaded in the in-memory topic graph - /// will not be included. + /// will not be included. This builds a throwaway snapshot on every call; it supports arbitrary subtree scoping (e.g., the + /// need not be the graph's root), which the live, incrementally maintained does not. Prefer that for hot paths that repeatedly reference the same graph's index. /// /// The instance of the to operate against; populated automatically by .NET. /// A dictionary of topics indexed by . public static TopicIndex GetTopicIndex(this Topic topic) => new(topic.FindAll()); + /*============================================================================================================================ + | METHOD: GET LIVE TOPIC INDEX + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Retrieves the live, incrementally maintained index of all topics in 's graph, indexed by . + /// + /// + /// Root-scoped regardless of which in the graph is passed. The returned instance is shared and + /// live: Entries appear as topics are attached, detached, or assigned an , maintained internally by + /// the library as those events occur. Callers must treat it as read-only and must not add to it directly. remains available where a snapshot of an arbitrary subtree is needed instead. + /// + /// The live index of topics, indexed by , for 's graph. + public static TopicIndex GetLiveTopicIndex(this Topic topic) => TopicIndexRegistry.GetOrBuild(topic.GetRootTopic()); + /*============================================================================================================================ | METHOD: GET ROOT TOPIC \---------------------------------------------------------------------------------------------------------------------------*/ From 4757d89f6c96cbc7b20bd0ab0d2935fda212e95e Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Mon, 27 Jul 2026 14:39:12 -0700 Subject: [PATCH 248/337] Use `GetLiveTopicIndex()` over `GetTopicIndex()` Instead of recalculating the `TopicIndex` with every request via `.referenceTopic.GetRootTopic().GetTopicIndex()`, now engage with the newly introduced live `TopicIndex` (a15ae85f, 273beeb2) using the `GetLiveTopicIndex()` method (a18d8d59). This completes the core implementation of the `TopicIndex` caching (#116). --- OnTopic.Data.Sql/SqlDataReaderExtensions.cs | 20 ++++++++--- OnTopic.Data.Sql/SqlTopicRepository.cs | 2 +- OnTopic.Tests/SqlTopicRepositoryTest.cs | 34 ++----------------- .../LazyLoadingTopicRepository.cs | 2 +- 4 files changed, 20 insertions(+), 38 deletions(-) diff --git a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs index e9d50b7b..eef2ae55 100644 --- a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs +++ b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs @@ -66,10 +66,14 @@ internal static class SqlDataReaderExtensions { /*-------------------------------------------------------------------------------------------------------------------------- | Establish topic index + >--------------------------------------------------------------------------------------------------------------------------- + | Null signals that no root has been established yet: AddTopic() uses that to distinguish between a graph's root and an + | orphaned row that couldn't be attached and was thus skipped. A referenceTopic supplies an live index; a cold load + | establishes its own root from the first row. \-------------------------------------------------------------------------------------------------------------------------*/ - var topics = referenceTopic is not null? referenceTopic.GetRootTopic().GetTopicIndex() : new(); + var topics = referenceTopic?.GetLiveTopicIndex(); var rootTopic = (Topic?)null; - var preExistingIds = new HashSet(topics.Keys); + var preExistingIds = new HashSet(topics?.Keys ?? []); var seedTopic = (Topic?)null; /*-------------------------------------------------------------------------------------------------------------------------- @@ -82,8 +86,11 @@ internal static class SqlDataReaderExtensions { var addedTopic = reader.AddTopic(topics, markDirty); var rawTopic = (ITopicBackingAccessor)addedTopic; - // The first topic returned is the root topic - rootTopic ??= addedTopic; + // The first topic returned is the root topic; materialize its live index so later rows can resolve against it + if (rootTopic is null) { + rootTopic = addedTopic; + topics ??= addedTopic.GetLiveTopicIndex(); + } // If loading the entire tree, the rootTopic is also the seedTopic if (seedTopicId < 0) { @@ -124,6 +131,11 @@ internal static class SqlDataReaderExtensions { } + /*-------------------------------------------------------------------------------------------------------------------------- + | An empty result set never established a root, leaving topics null; fall back to an empty index for the passes below + \-------------------------------------------------------------------------------------------------------------------------*/ + topics ??= new(); + /*-------------------------------------------------------------------------------------------------------------------------- | Read attributes \-------------------------------------------------------------------------------------------------------------------------*/ diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index 5584cba8..a6bd6a9c 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -398,7 +398,7 @@ public virtual async Task EnsureLoaded(Topic topic, TopicPayload payload, Cancel | DeferredAssociationCollection.SetValue() deduplicate those values so reprocessing doesn't accumulate duplicate entries in | the Deferred collection. \-------------------------------------------------------------------------------------------------------------------------*/ - var topics = topic.GetRootTopic().GetTopicIndex(); + var topics = topic.GetLiveTopicIndex(); var rawTopic = (ITopicBackingAccessor)topic; try { diff --git a/OnTopic.Tests/SqlTopicRepositoryTest.cs b/OnTopic.Tests/SqlTopicRepositoryTest.cs index a6b2b4a4..0306a32d 100644 --- a/OnTopic.Tests/SqlTopicRepositoryTest.cs +++ b/OnTopic.Tests/SqlTopicRepositoryTest.cs @@ -225,37 +225,6 @@ public async Task LoadTopicGraph_WithReference_ReturnsReference() { } - /*============================================================================================================================ - | TEST: LOAD TOPIC GRAPH: WITH EXTERNAL REFERENCE: RETURNS REFERENCE - \---------------------------------------------------------------------------------------------------------------------------*/ - /// - /// Calls with a record and - /// confirms that a topic with those values is returned. - /// - [Fact] - public async Task LoadTopicGraph_WithExternalReference_ReturnsReference() { - - using var topics = new TopicsDataTable(); - using var empty = new AttributesDataTable(); - using var references = new TopicReferencesDataTable(); - - var referenceTopic = new Topic("Web", "Container", null, 2); - - topics.AddRow(1, "Root", "Container"); - references.AddRow(1, "Test", 2); - - using var tableReader = new DataTableReader([topics, empty, empty, empty, references]); - - var topic = await tableReader.LoadTopicGraph(1, referenceTopic, false, cancellationToken: CancellationToken); - - Assert.NotNull(topic); - Assert.Equal(1, topic.Id); - Assert.Equal(2, topic.References.GetValue("Test")?.Id); - Assert.True(((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.References)); - Assert.False(topic.References.IsDirty()); - - } - /*============================================================================================================================ | TEST: LOAD TOPIC GRAPH: WITH DELETED REFERENCE: REMOVES EXISTING REFERENCE \---------------------------------------------------------------------------------------------------------------------------*/ @@ -1085,7 +1054,8 @@ public async Task FillChildren_FreshChildWithExtendedAttributesIncluded_Converge using var tableReader = new DataTableReader(topics); - var topicIndex = parent.GetTopicIndex(); + // Attach-first: the fresh child is indexed via the attach hook into the live index, not the passed-in lookup index + var topicIndex = parent.GetLiveTopicIndex(); await tableReader.FillChildren(parent, topicIndex, CancellationToken); diff --git a/OnTopic/Repositories/LazyLoadingTopicRepository.cs b/OnTopic/Repositories/LazyLoadingTopicRepository.cs index 336ca3de..9b7e7fa6 100644 --- a/OnTopic/Repositories/LazyLoadingTopicRepository.cs +++ b/OnTopic/Repositories/LazyLoadingTopicRepository.cs @@ -153,7 +153,7 @@ private async Task ResolveAssociations(Topic topic, TopicPayload payload, bool f var rawTopic = (ITopicBackingAccessor)topic; // Index the resident graph by id - var topicIndex = topic.GetRootTopic().GetTopicIndex(); + var topicIndex = topic.GetLiveTopicIndex(); // Resolve deferred relationship targets if (payload.HasFlag(TopicPayload.Relationships)) { From 9ef4189e047cf0b36c095cb2c772e7448df2a98f Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Mon, 27 Jul 2026 14:57:08 -0700 Subject: [PATCH 249/337] Skip orphaned topics in `AddTopic()` Previously, `AddTopic()` _always_ created a topic and indexed it. That included any "orphaned" topics that didn't have a parent in the index. As a result, those same topic would have any relationships wired up, ensuring they persisted in the topic graph and could be referenced, even though they weren't part of the hierarchy. This can happen due to lazy-loading (#111) and `Refresh()` where a topic is added or updated, but whose parent isn't yet loaded in the tree. If the parent(s) were preexisting and not themselves updated, then the parent(s) won't be present in the `GetUpdates()` load, and the update will be orphaned. This scenario wouldn't have occurred with eager loading, and is a newly introduced possibility due to lazy loading. --- OnTopic.Data.Sql/SqlDataReaderExtensions.cs | 118 ++++++++++++++------ 1 file changed, 85 insertions(+), 33 deletions(-) diff --git a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs index eef2ae55..6a6110d1 100644 --- a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs +++ b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs @@ -82,8 +82,12 @@ internal static class SqlDataReaderExtensions { Debug.WriteLine("SqlTopicRepository.Load(): AddTopic() [" + DateTime.Now + "]"); while (await reader.ReadAsync(cancellationToken).ConfigureAwait(false)) { - // Add the topic to the topic graph + // Add the topic to the topic graph; a null result means the row couldn't be attached and was skipped var addedTopic = reader.AddTopic(topics, markDirty); + if (addedTopic is null) { + continue; + } + var rawTopic = (ITopicBackingAccessor)addedTopic; // The first topic returned is the root topic; materialize its live index so later rows can resolve against it @@ -211,18 +215,33 @@ internal static class SqlDataReaderExtensions { | METHOD: ADD TOPIC \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Given the primary topic attributes from the TopicIndex view, establishes a barebones - /// instance and adds it to the collection. + /// Given the primary topic attributes from the TopicIndex view, establishes a barebones instance + /// and attaches it to its parent, if resolvable. /// + /// + /// Attach-first: A new row is never separately added to an index and then reconciled with its parent; assigning attaches it to the graph immediately, and the hook indexes + /// it as a side effect. A row whose parent cannot be resolved is unreachable from the returned graph and is skipped (i.e., + /// returns ), unless is itself , meaning no + /// root has been established yet for this load, in which case the row becomes the root of a fresh graph and is created + /// unattached. Callers must materialize a live index from that root before the next row is processed, so that the row can + /// resolve against it. + /// /// The with output from the GetTopics stored procedure. - /// A of topics to be loaded. + /// + /// The live index of topics resolved so far, or if this load hasn't yet established a root. + /// /// - /// Specified whether the target collection value should be marked as dirty, assuming the value changes. By default, it - /// will be marked dirty if the value is new or has changed from a previous value. By setting this parameter, that - /// behavior is overwritten to accept whatever value is submitted. This can be used, for instance, to prevent an update - /// from being persisted to the data store on . + /// Specifies whether the target collection value should be marked as dirty, assuming the value changes. By default, it will + /// be marked dirty if the value is new or has changed from a previous value. By setting this parameter, that behavior is + /// overwritten to accept whatever value is submitted. This can be used, for instance, to prevent an update from being + /// persisted to the data store on . /// - private static Topic AddTopic(this IDataReader reader, TopicIndex topics, bool? markDirty) { + /// + /// The resolved or newly created ; if the row is unreachable from the returned + /// graph and was skipped. + /// + private static Topic? AddTopic(this IDataReader reader, TopicIndex? topics, bool? markDirty) { /*-------------------------------------------------------------------------------------------------------------------------- | Identify attributes @@ -232,27 +251,43 @@ private static Topic AddTopic(this IDataReader reader, TopicIndex topics, bool? var contentType = reader.GetString("ContentType"); var parentId = reader.GetInteger("ParentID"); var wasDirty = false; + Topic current; /*-------------------------------------------------------------------------------------------------------------------------- - | Establish topic + | New row: Attach first, per the database ordering which guarantees parents are delivered before children \-------------------------------------------------------------------------------------------------------------------------*/ - if (!topics.TryGetValue(topicId, out var current)) { + if (topics is null || !topics.TryGetValue(topicId, out var existing)) { current = TopicFactory.Create(key, contentType, topicId); - topics.TryAdd(current.Id, current); + // Default to NotLoaded; a corresponding row in the version history dataset, if any, promotes this to Loaded ((ITopicBackingAccessor)current).VersionHistory.LoadState = LoadState.NotLoaded; + + // No root established yet: This row is the root of a fresh graph, so create it unattached + if (topics is null) { } + + // Parent is available: Attach immediately, and the hook indexes the new topic and its (empty) subtree + else if (parentId >= 0 && topics.TryGetValue(parentId, out var parentTopic)) { + current.Parent = parentTopic; + } + + // Parent is neither available nor previously returned: treat as an orphan and skip (generally unexpected) + else { + return null; + } + } + + /*-------------------------------------------------------------------------------------------------------------------------- + | Pre-existing row: Update in place, including re-parenting if it moved, assuming the new parent is available + \-------------------------------------------------------------------------------------------------------------------------*/ else { + current = existing; wasDirty = current.IsDirty(); current.Key = key; current.ContentType = contentType; - } - - /*-------------------------------------------------------------------------------------------------------------------------- - | Assign parent - \-------------------------------------------------------------------------------------------------------------------------*/ - if (parentId >= 0 && current.Parent?.Id != parentId && topics.TryGetValue(parentId, out var parentTopic)) { - current.Parent = parentTopic; + if (parentId >= 0 && current.Parent?.Id != parentId && topics.TryGetValue(parentId, out var newParent)) { + current.Parent = newParent; + } } /*-------------------------------------------------------------------------------------------------------------------------- @@ -328,7 +363,10 @@ internal static void SetIndexedAttributes(this IDataReader reader, TopicIndex to /*-------------------------------------------------------------------------------------------------------------------------- | Identify topic \-------------------------------------------------------------------------------------------------------------------------*/ - var current = topics[topicId]; + // Absent from topics means the topic was orphaned and skipped by AddTopic(); its attribute rows are ignored in kind + if (!topics.TryGetValue(topicId, out var current)) { + return; + } var rawTopic = (ITopicBackingAccessor)current; /*-------------------------------------------------------------------------------------------------------------------------- @@ -384,7 +422,10 @@ internal static void SetExtendedAttributes( /*-------------------------------------------------------------------------------------------------------------------------- | Identify the current topic \-------------------------------------------------------------------------------------------------------------------------*/ - var current = topics[topicId]; + // Absent from topics means the topic was orphaned and skipped by AddTopic(); its attribute rows are ignored in kind + if (!topics.TryGetValue(topicId, out var current)) { + return; + } var rawTopic = (ITopicBackingAccessor)current; /*-------------------------------------------------------------------------------------------------------------------------- @@ -457,7 +498,11 @@ internal static void SetRelationships(this IDataReader reader, TopicIndex topics /*-------------------------------------------------------------------------------------------------------------------------- | Identify affected topics \-------------------------------------------------------------------------------------------------------------------------*/ - var current = topics[sourceTopicId]; + // A source absent from topics was orphaned and skipped by AddTopic(); its relationship rows are skipped in kind, rather + // than resolved, so an orphan never registers on a target's IncomingRelationships + if (!topics.TryGetValue(sourceTopicId, out var current)) { + return; + } var rawTopic = (ITopicBackingAccessor)current; var related = (Topic?)null; @@ -514,7 +559,11 @@ internal static void SetReferences(this IDataReader reader, TopicIndex topics, b /*-------------------------------------------------------------------------------------------------------------------------- | Identify affected topics \-------------------------------------------------------------------------------------------------------------------------*/ - var current = topics[sourceTopicId]; + // A source absent from topics was orphaned and skipped by AddTopic(); its reference rows are skipped in kind, rather than + // resolved, so an orphan never registers on a target's IncomingRelationships + if (!topics.TryGetValue(sourceTopicId, out var current)) { + return; + } var rawTopic = (ITopicBackingAccessor)current; var referenced = (Topic?)null; @@ -545,25 +594,25 @@ internal static void SetReferences(this IDataReader reader, TopicIndex topics, b | METHOD: ADD CHILD TOPIC \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Processes a single row from the children result set of a GetTopics response: Adds the child to the index via , then stamps its Attributes.LoadState and Children.LoadState - /// based on the HasExtendedAttributes and HasChildren database hints. Returns - /// when the row represents the itself (which the stored procedure includes alongside its - /// children) so callers can skip it. + /// Processes a single row from the children result set of a GetTopics response: Attaches the child via , then stamps its Children.LoadState and Attributes.LoadState based on the HasChildren + /// and HasExtendedAttributes database hints. Returns when the row represents the itself (which the stored procedure includes alongside its children), or when + /// skipped it as an orphan, which is unexpected here. /// /// The , positioned at a row in the children result set. /// The topic whose children are being loaded; rows matching this ID are skipped. - /// The to populate. + /// The live of 's graph. private static Topic? AddChildTopic(this IDataReader reader, Topic parent, TopicIndex topics) { // Capture pre-existing status before AddTopic() introduces the topic to the index var wasPreExisting = topics.ContainsKey(reader.GetTopicId()); - // Add or update the topic in the index + // Add or update the topic in the index; parent is always available, so a null result here isn't expected in practice var addedTopic = reader.AddTopic(topics, markDirty: false); - // Skip the parent record, which the stored procedure returns alongside its children - if (addedTopic.Id == parent.Id) { + // Skip the parent record, which the stored procedure returns alongside its children, or for an orphaned row (unexpected) + if (addedTopic is null || addedTopic.Id == parent.Id) { return null; } @@ -634,7 +683,10 @@ internal static void SetVersionHistory(this IDataReader reader, TopicIndex topic /*-------------------------------------------------------------------------------------------------------------------------- | Identify topic \-------------------------------------------------------------------------------------------------------------------------*/ - var current = topics[topicId]; + // Absent from topics means the topic was orphaned and skipped by AddTopic(); its version rows are ignored in kind + if (!topics.TryGetValue(topicId, out var current)) { + return; + } var rawTopic = (ITopicBackingAccessor)current; /*-------------------------------------------------------------------------------------------------------------------------- From e37be61378d8d9456db997098a57947e0afef8f3 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Mon, 27 Jul 2026 15:29:38 -0700 Subject: [PATCH 250/337] Added unit test for orphaned topics in `Refresh()` This provides a test for the bug fix where we no longer index and, thus, potentially wire-up associations to "orphaned" topics (9ef4189e). --- OnTopic.Tests/SqlTopicRepositoryTest.cs | 39 +++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/OnTopic.Tests/SqlTopicRepositoryTest.cs b/OnTopic.Tests/SqlTopicRepositoryTest.cs index 0306a32d..74ca82fb 100644 --- a/OnTopic.Tests/SqlTopicRepositoryTest.cs +++ b/OnTopic.Tests/SqlTopicRepositoryTest.cs @@ -631,6 +631,45 @@ public async Task LoadTopicGraph_DisconnectedBatch_PreservesNotLoaded() { } + /*============================================================================================================================ + | TEST: LOAD TOPIC GRAPH: ORPHANED SOURCE: DOES NOT REGISTER INCOMING RELATIONSHIP + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Calls with a relationship row whose source is an orphan; i.e., its + /// ParentID doesn't resolve to a topic. Confirms the resident target's + /// gains no entry from it. + /// + /// + /// This can occur when the GetUpdates stored procedure returns updates to a topic whose parent hasn't yet been loaded in a + /// lazily loaded topic tree. As a result, processing its associations would leave the resident graph holding a dangling + /// reference to a topic that was otherwise discarded with the load. skips + /// the orphan s it desn't end up in the live index, and must, in + /// kind, skip its relationship rows instead of resolving them. + /// + [Fact] + public async Task LoadTopicGraph_OrphanedSource_DoesNotRegisterIncomingRelationship() { + + using var topics = new TopicsDataTable(); + using var empty = new AttributesDataTable(); + using var relationships = new RelationshipsDataTable(); + + topics.AddRow(1, "Root", "Container"); + topics.AddRow(2, "Target", "Page", 1); + topics.AddRow(99, "Orphan", "Page", 999); + relationships.AddRow(99, "Test", 2, false); + + using var tableReader = new DataTableReader([topics, empty, empty, relationships]); + + var topic = await tableReader.LoadTopicGraph(cancellationToken: CancellationToken); + + Assert.NotNull(topic); + + var target = topic.GetLiveTopicIndex()[2]; + + Assert.Empty(target.IncomingRelationships.GetValues("Test")); + + } + /*============================================================================================================================ | TEST: LOAD TOPIC GRAPH: WHOLE TREE LOAD: CONVERGES NON-LEAF REGION NODES \---------------------------------------------------------------------------------------------------------------------------*/ From 21e527751d04b076ac615de120e00d526d11b498 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Mon, 27 Jul 2026 15:52:58 -0700 Subject: [PATCH 251/337] Added unit test for `Refresh()` ordering When the `GetUpdates` stored procedure retrieves updates, it can include entirely new topics. And those entirely new topics can have children. A recent update fixes a bug by ensuring those topics are loaded parent first so that the parent is always processed and added to the topic index before the children, thus ensuring the latter aren't orphaned (0a30ecd7). This test ensures that, given that expected return, both a new parent and child get added to the topic graph correctly. --- OnTopic.Tests/SqlTopicRepositoryTest.cs | 44 ++++++++++++++++++++++--- 1 file changed, 39 insertions(+), 5 deletions(-) diff --git a/OnTopic.Tests/SqlTopicRepositoryTest.cs b/OnTopic.Tests/SqlTopicRepositoryTest.cs index 74ca82fb..f5c756a5 100644 --- a/OnTopic.Tests/SqlTopicRepositoryTest.cs +++ b/OnTopic.Tests/SqlTopicRepositoryTest.cs @@ -640,11 +640,11 @@ public async Task LoadTopicGraph_DisconnectedBatch_PreservesNotLoaded() { /// gains no entry from it. /// /// - /// This can occur when the GetUpdates stored procedure returns updates to a topic whose parent hasn't yet been loaded in a - /// lazily loaded topic tree. As a result, processing its associations would leave the resident graph holding a dangling - /// reference to a topic that was otherwise discarded with the load. skips - /// the orphan s it desn't end up in the live index, and must, in - /// kind, skip its relationship rows instead of resolving them. + /// This can occur when the GetTopicUpdates stored procedure returns updates to a topic whose parent hasn't yet been + /// loaded in a lazily loaded topic tree. As a result, processing its associations would leave the resident graph holding a + /// dangling reference to a topic that was otherwise discarded with the load. AddTopic() skips the orphan, so it + /// doesn't end up in the live index, and must, in kind, skip its + /// relationship rows instead of resolving them. /// [Fact] public async Task LoadTopicGraph_OrphanedSource_DoesNotRegisterIncomingRelationship() { @@ -670,6 +670,40 @@ public async Task LoadTopicGraph_OrphanedSource_DoesNotRegisterIncomingRelations } + /*============================================================================================================================ + | TEST: LOAD TOPIC GRAPH: REFRESH ORDERING: ATTACHES NEW PARENT AND CHILD + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Calls with a GetTopicUpdates-shaped batch introducing a new + /// parent followed by its new child, which is the ordering ORDER BY RangeLeft guarantees, and confirms both attach, + /// with the child under the new parent, and both appear in the graph's live index. + /// + /// + /// Pins the ordering contract that attach-first loading depends on: A new row's parent must already be loaded, or itself + /// just attached, for the row to attach rather than being skipped as an orphan. + /// + [Fact] + public async Task LoadTopicGraph_RefreshOrdering_AttachesNewParentAndChild() { + + var root = new Topic("Root", "Container", null, 1); + + using var topics = new TopicsDataTable(); + + topics.AddRow(50, "NewParent", "Container", 1); + topics.AddRow(51, "NewChild", "Page", 50); + + using var tableReader = new DataTableReader(topics); + + await tableReader.LoadTopicGraph(referenceTopic: root, cancellationToken: CancellationToken); + + var index = root.GetLiveTopicIndex(); + + Assert.True(index.ContainsKey(50)); + Assert.True(index.ContainsKey(51)); + Assert.Equal(50, index[51].Parent?.Id); + + } + /*============================================================================================================================ | TEST: LOAD TOPIC GRAPH: WHOLE TREE LOAD: CONVERGES NON-LEAF REGION NODES \---------------------------------------------------------------------------------------------------------------------------*/ From 0587bbc00fcc58285ee7f548d621c30058134aea Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Mon, 27 Jul 2026 15:55:04 -0700 Subject: [PATCH 252/337] Added unit tests for new `TopicIndexRegistry` Added unit tests for ensuring that the `TopicIndexRegistry` (a15ae85f ) is being properly maintained via its integration points (273beeb2). This ensures testing for the new `TopicIndex` caching (#116). --- OnTopic.Tests/TopicIndexRegistryTest.cs | 251 ++++++++++++++++++++++++ 1 file changed, 251 insertions(+) create mode 100644 OnTopic.Tests/TopicIndexRegistryTest.cs diff --git a/OnTopic.Tests/TopicIndexRegistryTest.cs b/OnTopic.Tests/TopicIndexRegistryTest.cs new file mode 100644 index 00000000..f25366df --- /dev/null +++ b/OnTopic.Tests/TopicIndexRegistryTest.cs @@ -0,0 +1,251 @@ +/*============================================================================================================================== +| Author Ignia, LLC +| Client Ignia, LLC +| Project Topics Library +\=============================================================================================================================*/ +using OnTopic.Collections.Specialized; +using OnTopic.Querying; +using OnTopic.Repositories; +using Xunit; + +namespace OnTopic.Tests; + +/*============================================================================================================================== +| CLASS: TOPIC INDEX REGISTRY TEST +\-----------------------------------------------------------------------------------------------------------------------------*/ +/// +/// Provides unit tests for the live, incrementally maintained , accessed via . +/// +[ExcludeFromCodeCoverage] +public class TopicIndexRegistryTest { + + /*============================================================================================================================ + | TEST: GET LIVE TOPIC INDEX: SAME GRAPH: RETURNS SAME INSTANCE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Calls twice on the same graph, confirming the same instance is + /// returned both times, and that a subsequently attached child is present without a rebuild. + /// + [Fact] + public void GetLiveTopicIndex_SameGraph_ReturnsSameInstance() { + + var root = new Topic("Root", "Container", null, 1); + + var firstIndex = root.GetLiveTopicIndex(); + var secondIndex = root.GetLiveTopicIndex(); + + Assert.Same(firstIndex, secondIndex); + + var child = new Topic("Child", "Page", root, 2); + + Assert.Same(child, firstIndex[2]); + + } + + /*============================================================================================================================ + | TEST: ON ATTACHED: SUBTREE: INDEXES DESCENDANTS + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Attaches a subtree of already populated instances under a graph with a live index and confirms every + /// non- descendant is indexed. + /// + [Fact] + public void OnAttached_Subtree_IndexesDescendants() { + + var root = new Topic("Root", "Container", null, 1); + var index = root.GetLiveTopicIndex(); + + var branch = new Topic("Branch", "Container", null, 2); + var leaf = new Topic("Leaf", "Page", branch, 3); + var newLeaf = new Topic("NewLeaf", "Page", branch); + + branch.Parent = root; + + Assert.Same(branch, index[2]); + Assert.Same(leaf, index[3]); + Assert.False(index.ContainsKey(newLeaf.Id)); + + } + + /*============================================================================================================================ + | TEST: ON DETACHED: SUBTREE: REMOVES DESCENDANTS AND SUPPORTS MOVE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Detaches a subtree from a graph with a live index and confirms its descendants are removed; then re-attaches it under a + /// different parent in the same graph and confirms they're restored. + /// + [Fact] + public void OnDetached_Subtree_RemovesDescendants_AndSupportsMove() { + + var root = new Topic("Root", "Container", null, 1); + var branchA = new Topic("BranchA", "Container", root, 2); + var branchB = new Topic("BranchB", "Container", root, 3); + var leaf = new Topic("Leaf", "Page", branchA, 4); + + var index = root.GetLiveTopicIndex(); + + Assert.True(index.ContainsKey(4)); + + branchA.Children.Remove(leaf.Key); + + Assert.False(index.ContainsKey(4)); + + leaf.Parent = branchB; + + Assert.True(index.ContainsKey(4)); + Assert.Same(branchB, index[4].Parent); + + } + + /*============================================================================================================================ + | TEST: ON ID ASSIGNED: MATERIALIZED INDEX: INDEXES TOPIC + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Attaches a new, unsaved to a graph with a live index, then assigns its , thus + /// simulating , and confirms it then appears in the index. + /// + [Fact] + public void OnIdAssigned_MaterializedIndex_IndexesTopic() { + + var root = new Topic("Root", "Container", null, 1); + var index = root.GetLiveTopicIndex(); + var newTopic = new Topic("New", "Page", root); + + Assert.True(newTopic.IsNew); + Assert.False(index.ContainsKey(newTopic.Id)); + + newTopic.Id = 42; + + Assert.Same(newTopic, index[42]); + + } + + /*============================================================================================================================ + | TEST: CLEAR ITEMS: MATERIALIZED INDEX: INVALIDATES + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Clears a topic's children and confirms the next call returns a + /// rebuilt index that no longer contains the cleared topics, at any depth. + /// + [Fact] + public void ClearItems_MaterializedIndex_Invalidates() { + + var root = new Topic("Root", "Container", null, 1); + var child = new Topic("Child", "Page", root, 2); + + _ = new Topic("Grandchild", "Page", child, 3); + + var firstIndex = root.GetLiveTopicIndex(); + + Assert.True(firstIndex.ContainsKey(2)); + Assert.True(firstIndex.ContainsKey(3)); + + root.Children.Clear(); + + var secondIndex = root.GetLiveTopicIndex(); + + Assert.False(secondIndex.ContainsKey(2)); + Assert.False(secondIndex.ContainsKey(3)); + + } + + /*============================================================================================================================ + | TEST: GET LIVE TOPIC INDEX: SEPARATE GRAPHS: RETURNS INDEPENDENT INDEXES + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Establishes two separate topic graphs and confirms their live indexes are independent of one another. + /// + [Fact] + public void GetLiveTopicIndex_SeparateGraphs_ReturnsIndependentIndexes() { + + var rootA = new Topic("RootA", "Container", null, 1); + var rootB = new Topic("RootB", "Container", null, 2); + + _ = new Topic("ChildA", "Page", rootA, 3); + + var indexA = rootA.GetLiveTopicIndex(); + var indexB = rootB.GetLiveTopicIndex(); + + Assert.NotSame(indexA, indexB); + Assert.True(indexA.ContainsKey(3)); + Assert.False(indexB.ContainsKey(3)); + + } + + /*============================================================================================================================ + | TEST: ON ATTACHED: RE-ROOTED GRAPH: DOES NOT RESURRECT STALE INDEX + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Builds the live index of a standalone graph, attaches its root under another graph (merging it in), detaches it again, + /// and confirms a subsequent call returns a freshly rebuilt index + /// rather than the stale, pre-merge one. + /// + /// + /// Evaluates both and directly, + /// since a topic that has been fully detached from its parent has no public path to being a root again ('s back-reference isn't cleared by removal alone, only by + /// assigning a new one). This test evaluates the internal hook contract, not a publicly reachable sequence. + /// + [Fact] + public void OnAttached_ReRootedGraph_DoesNotResurrectStaleIndex() { + + var standaloneRoot = new Topic("Standalone", "Container", null, 5); + + _ = new Topic("StandaloneChild", "Page", standaloneRoot, 6); + + var staleIndex = standaloneRoot.GetLiveTopicIndex(); + + Assert.True(staleIndex.ContainsKey(6)); + + var mainRoot = new Topic("Main", "Container", null, 1); + + _ = mainRoot.GetLiveTopicIndex(); + + TopicIndexRegistry.OnAttached(mainRoot, standaloneRoot); + TopicIndexRegistry.OnDetached(mainRoot, standaloneRoot); + + var rebuiltIndex = standaloneRoot.GetLiveTopicIndex(); + + Assert.NotSame(staleIndex, rebuiltIndex); + Assert.True(rebuiltIndex.ContainsKey(6)); + + } + + /*============================================================================================================================ + | TEST: ON ATTACHED: NOT LOADED INTERMEDIATE: INDEXES PHYSICAL DESCENDANTS + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Attaches a subtree whose intermediate node has but also + /// present children, and confirms every physical descendant is indexed regardless; detaches it and confirms every physical + /// descendant is pruned regardless. + /// + /// + /// traverses raw, bypassing the autoloading getter, and the registry's hooks + /// must not reintroduce a LoadState gate. + /// + [Fact] + public void OnAttached_NotLoadedIntermediate_IndexesPhysicalDescendants() { + + var root = new Topic("Root", "Container", null, 1); + var index = root.GetLiveTopicIndex(); + + var intermediate = new Topic("Intermediate", "Container", null, 2); + + _ = new Topic("PhysicalChild", "Page", intermediate, 3); + + ((ITopicBackingAccessor)intermediate).Children.LoadState = LoadState.NotLoaded; + + intermediate.Parent = root; + + Assert.True(index.ContainsKey(2)); + Assert.True(index.ContainsKey(3)); + + root.Children.Remove(intermediate.Key); + + Assert.False(index.ContainsKey(2)); + Assert.False(index.ContainsKey(3)); + + } + +} //Class \ No newline at end of file From ae279e955a9a2e8a3da4d177278464b3545fdee3 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Mon, 27 Jul 2026 16:59:28 -0700 Subject: [PATCH 253/337] Removed `_topicIdIndex` from cached repository Previously, the `CachedTopicRepository` managed its own ID (`_topicIdIndex`) and Key (`_topicKeyIndex`) indexes in response to events raised on the `ObservableTopicRepository` (d5084085). The `_topicIdIndex` is now maintained by the `TopicIndexRegistry` (a15ae85f, 273beeb2) which is now used on the `referenceTopic` (4757d89f, a18d8d59) as part of the `TopicIndex` cache (#116). With that now in place, the `_topicIdIndex` can be removed entirely. The `_topicKeyIndex` must remain. --- OnTopic.Data.Caching/CachedTopicRepository.cs | 59 +++++++++++-------- 1 file changed, 34 insertions(+), 25 deletions(-) diff --git a/OnTopic.Data.Caching/CachedTopicRepository.cs b/OnTopic.Data.Caching/CachedTopicRepository.cs index f95f2b1b..929b5429 100644 --- a/OnTopic.Data.Caching/CachedTopicRepository.cs +++ b/OnTopic.Data.Caching/CachedTopicRepository.cs @@ -3,6 +3,7 @@ | Client Ignia, LLC | Project Topics Library \=============================================================================================================================*/ +using OnTopic.Collections.Specialized; using OnTopic.Internal.Diagnostics; using OnTopic.Querying; using OnTopic.Repositories; @@ -26,7 +27,6 @@ public class CachedTopicRepository : TopicRepositoryDecorator, ITopicLazyLoader | VARIABLES \---------------------------------------------------------------------------------------------------------------------------*/ private readonly Topic _cache; - private readonly Dictionary _topicIdIndex = new(); private readonly Dictionary _topicKeyIndex = new(StringComparer.OrdinalIgnoreCase); private readonly HashSet _absentTopicIdIndex = new(); private readonly HashSet _absentUniqueKeyIndex = new(StringComparer.OrdinalIgnoreCase); @@ -78,7 +78,11 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos .GetResult(); /*-------------------------------------------------------------------------------------------------------------------------- - | Populate flat index from seeded topics + | Populate key index from seeded topics + >--------------------------------------------------------------------------------------------------------------------------- + | The live id index needs no seeding here: Any ITopicRepository.Load() call attaches its results directly into the graph + | of the referenceTopic it's given, which builds that topic's live index; the Root:Configuration load above did so via + | _cache, and every topic attached since keeps it current. \-------------------------------------------------------------------------------------------------------------------------*/ foreach (var topic in _cache.FindAll()) { IndexTopic(topic); @@ -116,10 +120,7 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos /*-------------------------------------------------------------------------------------------------------------------------- | Lookup by topic identifier; top up and return on a hit \-------------------------------------------------------------------------------------------------------------------------*/ - Topic? topic; - lock (_syncLock) { - _topicIdIndex.TryGetValue(topicId, out topic); - } + _cache.GetLiveTopicIndex().TryGetValue(topicId, out var topic); if (topic is not null) { await EnsureLoaded(topic, payload, isRecursive).ConfigureAwait(false); return topic; @@ -149,11 +150,9 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos return null; } - // Return the topic from the cache - lock (_syncLock) { - _topicIdIndex.TryGetValue(topicId, out var result); - return result; - } + // Return the topic from the cache; the TopicIndexRegistry hooks indexed it as it was merged above + _cache.GetLiveTopicIndex().TryGetValue(topicId, out var result); + return result; } @@ -288,6 +287,11 @@ public virtual async Task EnsureLoaded(Topic topic, TopicPayload payload, Cancel /// for cases where the isRecursive parameter was specified on . /// Ancestors pulled in via @LoadAscendants sit above the topic, so , /// which only walks downward, never reaches them; they are indexed by walking up the parent chain instead. + /// + /// The live id index needs no attention here, as it is managed via the before this event + /// even fires. A historical version load ( not ) is skipped + /// entirely: Its topic is never attached to the resident graph, so it must not enter the key index either. + /// /// protected override void OnTopicLoaded(TopicLoadEventArgs args) { @@ -295,12 +299,17 @@ protected override void OnTopicLoaded(TopicLoadEventArgs args) { Contract.Requires(args); base.OnTopicLoaded(args); + // Historical version loads are not part of the resident graph; neither index should reflect them + if (args.Version is not null) { + return; + } + lock (_syncLock) { // Index the loaded topic and any descendants that came back attached; FindAll() is lazy-safe and naturally returns just - // the topic itself when nothing further is present, so this is correct whether or not the load was recursive + // the topic itself when nothing further is present, so this is correct whether or not the load was recursive. foreach (var topic in args.Topic.FindAll()) { - if (_topicIdIndex.ContainsKey(topic.Id)) { + if (_topicKeyIndex.ContainsKey(topic.GetUniqueKey())) { continue; } IndexTopic(topic); @@ -312,7 +321,7 @@ protected override void OnTopicLoaded(TopicLoadEventArgs args) { // Walk up from the parent, stopping at the first already indexed ancestor: The cache is always rooted, so everything // above an existing ancestor is itself already loaded and indexed. for (var ancestor = args.Topic.Parent; ancestor is not null; ancestor = ancestor.Parent) { - if (_topicIdIndex.ContainsKey(ancestor.Id)) { + if (_topicKeyIndex.ContainsKey(ancestor.GetUniqueKey())) { break; } IndexTopic(ancestor); @@ -329,7 +338,8 @@ protected override void OnTopicLoaded(TopicLoadEventArgs args) { /// Adds newly created topics to the flat index. When the save is recursive, all present descendants are indexed as well, /// since only one event fires for the root of a recursive save. Also clears any /// entries known to be missing so that a previously missing ID or key that is now created can be found on subsequent - /// lookups. + /// lookups. The live id index needs no attention here: 's setter already indexed each newly created + /// topic, via the registry's hooks, at the moment its persisted identifier was assigned. /// protected override void OnTopicSaved(TopicSaveEventArgs args) { @@ -354,7 +364,9 @@ protected override void OnTopicSaved(TopicSaveEventArgs args) { /// /// Removes the deleted topic and all of its descendants from the flat index. Called after the topic has been detached from /// its parent's collection but before the topic graph is torn down, so on the deleted topic still returns the full subtree. + /// "TopicExtensions.FindAll(Topic)"/> on the deleted topic still returns the full subtree. The live id index needs no + /// attention here: detaches the topic from its parent before raising + /// this event, so the registry's detach hook has already pruned the subtree from it. /// protected override void OnTopicDeleted(TopicEventArgs args) { @@ -362,10 +374,9 @@ protected override void OnTopicDeleted(TopicEventArgs args) { Contract.Requires(args); base.OnTopicDeleted(args); - // Remove the deleted subtree from both indices + // Remove the deleted subtree from the key index lock (_syncLock) { foreach (var topic in args.Topic.FindAll()) { - _topicIdIndex.Remove(topic.Id); _topicKeyIndex.Remove(topic.GetUniqueKey()); } } @@ -445,16 +456,14 @@ private void RekeyTopicSubtree(Topic topic, string oldRootUniqueKey) { | METHOD: INDEX TOPIC \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Adds or updates in both flat indexes. + /// Adds or updates in the unique-key index. /// /// - /// Callers are responsible for holding before invoking this method, except during construction - /// where single-threaded access is guaranteed. + /// The live id index () is maintained separately by the hooks, so needs no counterpart here. Callers are responsible for holding + /// before invoking this method, except during construction where single-threaded access is guaranteed. /// - private void IndexTopic(Topic topic) { - _topicIdIndex[topic.Id] = topic; - _topicKeyIndex[topic.GetUniqueKey()] = topic; - } + private void IndexTopic(Topic topic) => _topicKeyIndex[topic.GetUniqueKey()] = topic; /*============================================================================================================================ | METHOD: ENSURE LOADED From b7284fe5f6505a76d2f71fbd6a9931a38329abc4 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Mon, 27 Jul 2026 18:03:25 -0700 Subject: [PATCH 254/337] Added unit tests for ID index in cached test With the `TopicIndex` migrated out of `CachedTopicRepository` (ae279e95) and into the new `TopicIndexRegistry` (a15ae85f, 273beeb2) as part of the `TopicIndex` cache project (#116), it's worth adding a couple of tests to the `CachedTopicRepository` itself to ensure it's properly reflecting the underlying `TopicIndexRegistry`, as an addition to the `TopicIndexRegistry`'s own tests (ae279e95). --- OnTopic.Tests/CachedTopicRepositoryTest.cs | 132 +++++++++++++++++++++ 1 file changed, 132 insertions(+) diff --git a/OnTopic.Tests/CachedTopicRepositoryTest.cs b/OnTopic.Tests/CachedTopicRepositoryTest.cs index 880896c3..2c464ae1 100644 --- a/OnTopic.Tests/CachedTopicRepositoryTest.cs +++ b/OnTopic.Tests/CachedTopicRepositoryTest.cs @@ -4,8 +4,10 @@ | Project Topics Library \=============================================================================================================================*/ using System.Data; +using OnTopic.Collections.Specialized; using OnTopic.Data.Caching; using OnTopic.Data.Sql; +using OnTopic.Metadata; using OnTopic.Querying; using OnTopic.Repositories; using OnTopic.TestDoubles.LazyLoading; @@ -215,4 +217,134 @@ public async Task EnsureLoaded_DeferredAssociationFallbackWithResidentTargetPare } + /*============================================================================================================================ + | TEST: DELETE: LOADED TOPIC: SUBSEQUENT LOAD DOES NOT RETURN DETACHED INSTANCE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Deletes a loaded topic and confirms it is absent from ; i.e., the + /// detach hook in pruned it, since no + /// longer does so. + /// + /// + /// 's DeleteTopic doesn't actually do anything: The row survives in its store, + /// unlike a real deletion. That's exploited for the follow-up assertions: A subsequent + /// Load() by ID and then by unique key, both still find a row and reattach a fresh instance. If either index had + /// retained a stale entry instead of being pruned by e.g., the detach hook , that lookup would have returned the old, now-detached instance directly, without ever falling through to the inner + /// repository, so the fresh instances are themselves evidence both stale entries are gone, even though this isn't how a + /// real repository handles a delete. + /// + [Fact] + public async Task Delete_LoadedTopic_SubsequentLoadDoesNotReturnDetachedInstance() { + + var inner = new FakeSqlTopicRepository() + .AddTopic(1, "Root", "Container", null) + .AddTopic(2, "Web", "Page", 1) + .AddTopic(3, "Web_0", "Page", 2); + + var cache = new CachedTopicRepository(inner); + var root = await cache.Load("Root"); + var web = await cache.Load("Web"); + var web0 = await cache.Load("Web:Web_0"); + + Assert.Contains(web!.Children, child => child.Id == web0!.Id); + + await cache.Delete(web0!, isRecursive: false); + + Assert.DoesNotContain(web.Children, child => child.Id == web0!.Id); + Assert.False(root!.GetLiveTopicIndex().ContainsKey(web0!.Id)); + + var reloadedById = await cache.Load(web0!.Id); + + Assert.NotSame(web0, reloadedById); + + var reloadedByKey = await cache.Load("Web:Web_0"); + + Assert.NotSame(web0, reloadedByKey); + + } + + /*============================================================================================================================ + | TEST: SAVE: NEW TOPIC: RESOLVES VIA LOAD WITHOUT FALLBACK + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Saves a newly created, unsaved under a resident parent, then calls for its newly assigned ID and confirms the same + /// instance is returned directly from the live index, with no fall-through to the inner repository. Ensures the setter's indexing hook from makes a freshly saved topic resolvable by ID. + /// + [Fact] + public async Task Save_NewTopic_ResolvesViaLoadWithoutFallback() { + + var inner = new FakeSqlTopicRepository() + .AddTopic(1, "Root", "Container", null); + + var cache = new CachedTopicRepository(inner); + var root = await cache.Load("Root"); + + // Establish a minimal content type graph directly on the live root, required by Save()'s content type validation + var configuration = new Topic("Configuration", "Container", root); + var contentTypes = new ContentTypeDescriptor("ContentTypes", "ContentTypeDescriptor", configuration); + + _ = new ContentTypeDescriptor("Page", "ContentTypeDescriptor", contentTypes); + + var newChild = new Topic("NewChild", "Page", root); + + Assert.True(newChild.IsNew); + + await cache.Save(newChild); + + Assert.False(newChild.IsNew); + + var loaded = await cache.Load(newChild.Id); + + Assert.Same(newChild, loaded); + + } + + /*============================================================================================================================ + | TEST: SAVE: RECURSIVE NEW TOPICS: RESOLVE VIA LOAD WITHOUT FALLBACK + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Recursively saves a newly created parent with a newly created child underneath it, then calls for each of their newly assigned IDs and confirms both + /// resolve directly from the live index, with no fall-through to the inner repository. + /// + /// + /// Unlike , which saves a single topic, this ensures that the + /// setter's indexing hook also fires correctly for a child of a parent that was itself just assigned + /// an ID moments earlier in the same recursive save; i.e., , walked from + /// the child at the moment its own ID is assigned, correctly reaches _cache through the freshly attached parent. + /// + [Fact] + public async Task Save_RecursiveNewTopics_ResolveViaLoadWithoutFallback() { + + var inner = new FakeSqlTopicRepository() + .AddTopic(1, "Root", "Container", null); + + var cache = new CachedTopicRepository(inner); + var root = await cache.Load("Root"); + + // Establish a minimal content type graph directly on the live root, required by Save()'s content type validation + var configuration = new Topic("Configuration", "Container", root); + var contentTypes = new ContentTypeDescriptor("ContentTypes", "ContentTypeDescriptor", configuration); + + _ = new ContentTypeDescriptor("Page", "ContentTypeDescriptor", contentTypes); + + var newParent = new Topic("NewParent", "Page", root); + var newChild = new Topic("NewChild", "Page", newParent); + + await cache.Save(newParent, isRecursive: true); + + Assert.False(newParent.IsNew); + Assert.False(newChild.IsNew); + + var loadedParent = await cache.Load(newParent.Id); + var loadedChild = await cache.Load(newChild.Id); + + Assert.Same(newParent, loadedParent); + Assert.Same(newChild, loadedChild); + + } + } //Class \ No newline at end of file From fa60597e37fc56b8b19856c61aad447621e89f5a Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Mon, 27 Jul 2026 19:22:33 -0700 Subject: [PATCH 255/337] Remove duplicated unit tests With the introduction of the `LazyLoadingTopicRepositoryTest` (db8fbe83), many of the tests previously applied to the `TopicRepositoryBaseTest` (dedb2af6, d7c81d6c, c8bb0820, e2b8f75a, 60276b84) were duplicated, or subsequently covered by new tests, and should have been handled as a migration. Whoops. --- OnTopic.Tests/TopicRepositoryBaseTest.cs | 229 ----------------------- 1 file changed, 229 deletions(-) diff --git a/OnTopic.Tests/TopicRepositoryBaseTest.cs b/OnTopic.Tests/TopicRepositoryBaseTest.cs index 523dacda..f8635a95 100644 --- a/OnTopic.Tests/TopicRepositoryBaseTest.cs +++ b/OnTopic.Tests/TopicRepositoryBaseTest.cs @@ -1194,25 +1194,6 @@ public async Task Save_TopicMovedEvent_IsRaised() { } - /*============================================================================================================================ - | TEST: SAVE: NEW TOPIC: STAMPS RESOLVER - \---------------------------------------------------------------------------------------------------------------------------*/ - /// - /// Saves a new and confirms that the repository stamps a onto it so - /// that deferred boundaries can be populated on demand after the save. - /// - [Fact] - public async Task Save_NewTopic_StampsResolver() { - - var parent = await _topicRepository.Load("Root:Web:Web_3:Web_3_0"); - var topic = new Topic("Test", "Page", parent); - - await _topicRepository.Save(topic); - - Assert.NotNull(((ITopicLazyLoadable)topic).Loader); - - } - /*============================================================================================================================ | TEST: SAVE: NOT LOADED CHILDREN: SKIPS RECURSIVE DESCENT \---------------------------------------------------------------------------------------------------------------------------*/ @@ -1235,27 +1216,6 @@ public async Task Save_NotLoadedChildren_SkipsRecursiveDescent() { } - /*============================================================================================================================ - | TEST: ENSURE LOADED: EXTENDED ATTRIBUTES NOT LOADED: MARKS LOADED - \---------------------------------------------------------------------------------------------------------------------------*/ - /// - /// Loads a whose extended-attribute boundary has been manually set to - /// and confirms that promotes the boundary - /// to via the 's fill. - /// - [Fact] - public async Task EnsureLoaded_ExtendedAttributesNotLoaded_MarksLoaded() { - - var topic = await _topicRepository.Load(11111); - var rawTopic = (ITopicLazyLoadable)topic!; - - topic!.Attributes.LoadState = LoadState.NotLoaded; - await rawTopic.EnsureLoaded(TopicPayload.ExtendedAttributes); - - Assert.True(rawTopic.IsLoaded(TopicPayload.ExtendedAttributes)); - - } - /*============================================================================================================================ | TEST: ENSURE LOADED: MIXED BOUNDARIES: SKIPS LOADED BOUNDARIES \---------------------------------------------------------------------------------------------------------------------------*/ @@ -1279,122 +1239,6 @@ public async Task EnsureLoaded_MixedBoundaries_SkipsLoadedBoundaries() { } - /*============================================================================================================================ - | TEST: ENSURE LOADED: RELATIONSHIPS NOT LOADED: MARKS LOADED - \---------------------------------------------------------------------------------------------------------------------------*/ - /// - /// Loads a whose relationship boundary has been manually set to - /// and confirms that promotes the boundary - /// to via the 's fill. - /// - /// - /// On-demand fetching of non-resident relationship targets happens via LoadDeferredAssociations() on , which only invokes from its own - /// EnsureLoaded()— does not resolve deferred targets itself. This test's stub fill - /// simply marks the boundary without resolving the deferred target. - /// - [Fact] - public async Task EnsureLoaded_RelationshipsNotLoaded_MarksLoaded() { - - var topic = await _topicRepository.Load(11111); - var rawTopic = (ITopicLazyLoadable)topic!; - - topic!.Relationships.Deferred.Add(new("_stub", 11111)); - await rawTopic.EnsureLoaded(TopicPayload.Relationships); - - Assert.True(rawTopic.IsLoaded(TopicPayload.Relationships)); - - } - - /*============================================================================================================================ - | TEST: ENSURE LOADED: REFERENCES NOT LOADED: MARKS LOADED - \---------------------------------------------------------------------------------------------------------------------------*/ - /// - /// Loads a whose reference boundary has been manually set to and - /// confirms that promotes the boundary to - /// via the 's fill. - /// - /// - /// On-demand fetching of non-resident reference targets happens via LoadDeferredAssociations() on , which only invokes from its own - /// EnsureLoaded()— does not resolve deferred targets itself. This test's stub fill - /// simply marks the boundary without resolving the deferred target. - /// - [Fact] - public async Task EnsureLoaded_ReferencesNotLoaded_MarksLoaded() { - - var topic = await _topicRepository.Load(11111); - var rawTopic = (ITopicLazyLoadable)topic!; - - topic!.References.Deferred.Add(new("_stub", 11111)); - await rawTopic.EnsureLoaded(TopicPayload.References); - - Assert.True(rawTopic.IsLoaded(TopicPayload.References)); - - } - - /*============================================================================================================================ - | TEST: IS LOADED: CHILDREN NOT LOADED STATE: TRIGGERS ENSURE LOADED - \---------------------------------------------------------------------------------------------------------------------------*/ - /// - /// Loads a , marks its as , then accesses - /// the getter. Verifies that the autoload fires, promoting the boundary to via the 's fill. - /// - [Fact] - public async Task IsLoaded_ChildrenNotLoadedState_TriggersEnsureLoaded() { - - var topic = await _topicRepository.Load(11111); - var rawTopic = (ITopicLazyLoadable)topic!; - - rawTopic.SetLoadState(TopicPayload.Children, LoadState.NotLoaded); - _ = topic.Children; - - Assert.True(rawTopic.IsLoaded(TopicPayload.Children)); - - } - - /*============================================================================================================================ - | TEST: IS LOADED: CHILDREN LOADED STATE: DOES NOT CALL RESOLVER - \---------------------------------------------------------------------------------------------------------------------------*/ - /// - /// Loads a whose is already and accesses - /// the getter. Verifies that the boundary stays without the - /// resolver being called redundantly. - /// - [Fact] - public async Task IsLoaded_ChildrenLoadedState_DoesNotCallResolver() { - - var topic = await _topicRepository.Load(11111); - var rawTopic = (ITopicLazyLoadable)topic!; - - Assert.True(rawTopic.IsLoaded(TopicPayload.Children)); - _ = topic.Children; - - Assert.True(rawTopic.IsLoaded(TopicPayload.Children)); - - } - - /*============================================================================================================================ - | TEST: IS LOADED: RELATIONSHIPS NOT LOADED STATE: TRIGGERS ENSURE LOADED - \---------------------------------------------------------------------------------------------------------------------------*/ - /// - /// Loads a , marks its as , then - /// accesses the getter. Verifies that the autoload fires, promoting the boundary to - /// via the 's fill. - /// - [Fact] - public async Task IsLoaded_RelationshipsNotLoadedState_TriggersEnsureLoaded() { - - var topic = await _topicRepository.Load(11111); - - topic!.Relationships.Deferred.Add(new("_stub", 11111)); - _ = topic.Relationships; - - Assert.True(((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.Relationships)); - - } - /*============================================================================================================================ | TEST: IS LOADED: RELATIONSHIPS LOADED STATE: DOES NOT CALL RESOLVER \---------------------------------------------------------------------------------------------------------------------------*/ @@ -1416,26 +1260,6 @@ public async Task IsLoaded_RelationshipsLoadedState_DoesNotCallResolver() { } - /*============================================================================================================================ - | TEST: IS LOADED: REFERENCES NOT LOADED STATE: TRIGGERS ENSURE LOADED - \---------------------------------------------------------------------------------------------------------------------------*/ - /// - /// Loads a , marks its as , then - /// accesses the getter. Verifies that the autoload fires, promoting the boundary to - /// via the 's fill. - /// - [Fact] - public async Task IsLoaded_ReferencesNotLoadedState_TriggersEnsureLoaded() { - - var topic = await _topicRepository.Load(11111); - - topic!.References.Deferred.Add(new("_stub", 11111)); - _ = topic.References; - - Assert.True(((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.References)); - - } - /*============================================================================================================================ | TEST: IS LOADED: REFERENCES LOADED STATE: DOES NOT CALL RESOLVER \---------------------------------------------------------------------------------------------------------------------------*/ @@ -1457,27 +1281,6 @@ public async Task IsLoaded_ReferencesLoadedState_DoesNotCallResolver() { } - /*============================================================================================================================ - | TEST: IS LOADED: CHILDREN NOT LOADED: MARKS LOADED - \---------------------------------------------------------------------------------------------------------------------------*/ - /// - /// Loads a whose has been manually set to and confirms that promotes the - /// boundary to via the 's fill. - /// - [Fact] - public async Task EnsureLoaded_ChildrenNotLoaded_MarksLoaded() { - - var topic = await _topicRepository.Load(11111); - var rawTopic = (ITopicLazyLoadable)topic!; - - rawTopic.SetLoadState(TopicPayload.Children, LoadState.NotLoaded); - await rawTopic.EnsureLoaded(TopicPayload.Children); - - Assert.True(rawTopic.IsLoaded(TopicPayload.Children)); - - } - /*============================================================================================================================ | TEST: MOVE: TOPIC MOVED EVENT: IS RAISED \---------------------------------------------------------------------------------------------------------------------------*/ @@ -1551,38 +1354,6 @@ public async Task EnsureLoaded_Relationships_AlreadyLoaded_SkipsFill() { } - /*============================================================================================================================ - | TEST: LOAD: WITH ASCENDANTS: STAMPS ASCENDANT RESOLVERS - \---------------------------------------------------------------------------------------------------------------------------*/ - /// - /// Calls on a standalone instance—i.e., not - /// wrapped by , and never itself passed to Load() before—for a deeply nested - /// topic, and confirms that an ascendant is nonetheless stamped with an , so its own - /// deferred payload can still be lazy-loaded. - /// - /// - /// Uses a fresh rather than the shared field: The latter - /// is wrapped by in the constructor, whose own seeding recursively stamps the entire - /// (eagerly loaded) stub tree via , which would mask whether ascendant stamping actually comes - /// from this test's Load() call. - /// - [Fact] - public async Task Load_WithAscendants_StampsAscendantResolvers() { - - // Arrange: use a standalone repository, never wrapped by CachedTopicRepository - var topicRepository = new StubTopicRepository(); - - // Act: load a deeply nested topic - var topic = await topicRepository.Load("Root:Web:Web_3:Web_3_1:Web_3_1_0"); - - // An ascendant that was never itself the target of a Load() call is still stamped - var ascendant = topic?.Parent?.Parent; - - Assert.NotNull(ascendant); - Assert.NotNull((ascendant as ITopicLazyLoadable)?.Loader); - - } - /*============================================================================================================================ | TEST: MOVE: SAME LOCATION: EVENT NOT RAISED \---------------------------------------------------------------------------------------------------------------------------*/ From 3338fed3a6a3c26a7e351eb58556322a1286c468 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Mon, 27 Jul 2026 19:23:17 -0700 Subject: [PATCH 256/337] Migrate and improve unit tests tests The five tests removed from `TopicRepositoryBaseTest` weren't already covered by `LazyLoadingTopicRepositoryTest` yet, and thus weren't deleted with the previous batch (fa60597e). In this batch, I migrate them over and improve them to better account for the current state and context, with the two `IsLoaded_*LoadedState_DoesNotCallResolver` tests (e2b8f75a, e2b8f75a) now replaced with the new `*_AccessedTwice_FetchesOnce` tests, the `EnsureLoaded_MixedBoundaries_SkipsLoadedBoundaries()` test (dedb2af6) now replaced with `EnsureLoaded_Properties_OnlyFetchesPendingProperty`, and the `EnsureLoaded_WithMissingRelationshipTarget_ResolvesAndConnects()` and `EnsureLoaded_Relationships_AlreadyLoaded_SkipsFill()` tests (3100cf6f) now replaced with `EnsureLoaded_MissingRelationshipTarget_ResolvesAndConnects` and `EnsureLoaded_Relationships_AlreadyLoaded_SkipsFill`. These were all migrated to `LazyLoadingTopicRepositoryTest` with some modifications to improve the tests. This pertains to the testing of the lazy-loading infrastructure (#111). --- .../LazyLoadingTopicRepositoryTest.cs | 115 +++++++++++++++++- OnTopic.Tests/TopicRepositoryBaseTest.cs | 114 ----------------- 2 files changed, 114 insertions(+), 115 deletions(-) diff --git a/OnTopic.Tests/LazyLoadingTopicRepositoryTest.cs b/OnTopic.Tests/LazyLoadingTopicRepositoryTest.cs index aeaf022e..9969f7b8 100644 --- a/OnTopic.Tests/LazyLoadingTopicRepositoryTest.cs +++ b/OnTopic.Tests/LazyLoadingTopicRepositoryTest.cs @@ -275,6 +275,71 @@ public async Task EnsureLoaded_AlreadyLoaded_DoesNotFetch() { } + /*============================================================================================================================ + | TEST: RELATIONSHIPS: ACCESSED TWICE: FETCHES ONCE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Touches twice on a topic with a resolvable target and confirms the record store is + /// only fetched once, via the double's per-topic, per-property fetch-count spy. + /// + [Fact] + public async Task Relationships_AccessedTwice_FetchesOnce() { + + var topic = await _loadingTopicRepository.Load("Root:Web:Web_1"); + + _ = topic!.Relationships.GetValues("Related"); + _ = topic.Relationships.GetValues("Related"); + + Assert.Equal(1, _loadingTopicRepository.GetFetchCount(topic.Id, TopicPayload.Relationships)); + + } + + /*============================================================================================================================ + | TEST: REFERENCES: ACCESSED TWICE: FETCHES ONCE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Touches twice on a topic with a resolvable target and confirms the record store is only + /// fetched once, via the double's per-topic, per-property fetch-count spy. + /// + [Fact] + public async Task References_AccessedTwice_FetchesOnce() { + + var topic = await _loadingTopicRepository.Load("Root:Web:Web_1"); + + _ = topic!.References.Contains("BaseTopic"); + _ = topic.References.Contains("BaseTopic"); + + Assert.Equal(1, _loadingTopicRepository.GetFetchCount(topic.Id, TopicPayload.References)); + + } + + /*============================================================================================================================ + | TEST: ENSURE LOADED: MIXED PROPERTIES: ONLY FETCHES PENDING PROPERTY + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Loads for a topic that also carries an unloaded extended attribute, then calls with both properties requested + /// together, and confirms only the still-pending property is fetched: The + /// already loaded property is filtered out and left untouched, per the fetch-count spy. + /// + [Fact] + public async Task EnsureLoaded_Properties_OnlyFetchesPendingProperty() { + + var topic = await _loadingTopicRepository.Load("Root:Web:Web_0:Web_0_0"); + var rawTopic = (ITopicLazyLoadable)topic!; + + await rawTopic.EnsureLoaded(TopicPayload.Children, cancellationToken: CancellationToken); + await rawTopic.EnsureLoaded( + TopicPayload.Children | TopicPayload.ExtendedAttributes, + cancellationToken: CancellationToken + ); + + Assert.Equal(1, _loadingTopicRepository.GetFetchCount(topic.Id, TopicPayload.Children)); + Assert.Equal(1, _loadingTopicRepository.GetFetchCount(topic.Id, TopicPayload.ExtendedAttributes)); + Assert.Equal("Extended body content for Web_0_0.", topic.Attributes.GetValue("Body")); + + } + #endregion #region E: Recursive Lazy Descent @@ -482,6 +547,29 @@ public async Task EnsureLoaded_StaleReferenceTarget_IsDiscarded() { } + /*============================================================================================================================ + | TEST: ENSURE LOADED: MISSING RELATIONSHIP TARGET: RESOLVES AND CONNECTS + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Calls on a topic whose Relationships.LoadState is NotLoaded + /// , confirming that the loader re-queries for the topic's relationships, loads a target initially absent from the + /// cache, and connects the edge. The relationship-target complement to . + /// + [Fact] + public async Task EnsureLoaded_MissingRelationshipTarget_ResolvesAndConnects() { + + // The cache seeds only Root and Root:Configuration; "Web" (id 10000) is initially absent from the cache + var root = (await _cachedTopicRepository.Load(-1))!; + ((ITopicBackingAccessor)root).Relationships.Deferred.Add(new("_stub", 10000)); + + await _cachedTopicRepository.EnsureLoaded(root, TopicPayload.Relationships, cancellationToken: CancellationToken); + + Assert.Equal(LoadState.Loaded, root.Relationships.LoadState); + Assert.Equal(10000, root.Relationships.GetValues("_stub")[0].Id); + + } + /*============================================================================================================================ | TEST: ENSURE LOADED: MISSING REFERENCE TARGET: RESOLVES AND CONNECTS \---------------------------------------------------------------------------------------------------------------------------*/ @@ -489,7 +577,7 @@ public async Task EnsureLoaded_StaleReferenceTarget_IsDiscarded() { /// Calls on a topic whose References.LoadState is NotLoaded, /// confirming that the loader re-queries for the topic's references, loads a target initially absent from the cache, and /// connects the edge. The reference-target complement to . + /// "EnsureLoaded_MissingRelationshipTarget_ResolvesAndConnects"/>. /// [Fact] public async Task EnsureLoaded_MissingReferenceTarget_ResolvesAndConnects() { @@ -505,6 +593,31 @@ public async Task EnsureLoaded_MissingReferenceTarget_ResolvesAndConnects() { } + /*============================================================================================================================ + | TEST: ENSURE LOADED: RELATIONSHIPS: ALREADY LOADED: SKIPS FILL + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Calls on a topic whose relationships are already and confirms it returns immediately without re-querying the underlying record store, per the + /// inner 's fetch-count spy. + /// + [Fact] + public async Task EnsureLoaded_Relationships_AlreadyLoaded_SkipsFill() { + + var stub = new StubLazyLoadingTopicRepository(); + var cache = new CachedTopicRepository(stub); + + // The root's relationships start as Loaded (Deferred is empty); no fetch has been recorded against it + var root = (await cache.Load(-1))!; + var fetchesAfterLoad = stub.TotalFetches; + + await cache.EnsureLoaded(root, TopicPayload.Relationships, cancellationToken: CancellationToken); + + Assert.Equal(LoadState.Loaded, root.Relationships.LoadState); + Assert.Equal(fetchesAfterLoad, stub.TotalFetches); + + } + #endregion #region I: Decorator Stamp Precedence diff --git a/OnTopic.Tests/TopicRepositoryBaseTest.cs b/OnTopic.Tests/TopicRepositoryBaseTest.cs index f8635a95..e97be70c 100644 --- a/OnTopic.Tests/TopicRepositoryBaseTest.cs +++ b/OnTopic.Tests/TopicRepositoryBaseTest.cs @@ -1216,71 +1216,6 @@ public async Task Save_NotLoadedChildren_SkipsRecursiveDescent() { } - /*============================================================================================================================ - | TEST: ENSURE LOADED: MIXED BOUNDARIES: SKIPS LOADED BOUNDARIES - \---------------------------------------------------------------------------------------------------------------------------*/ - /// - /// Calls with a mixed set of flags, - /// including one already set to and one , and confirms that - /// only the pending boundary is forwarded to the resolver, leaving the already-loaded boundary unchanged. - /// - [Fact] - public async Task EnsureLoaded_MixedBoundaries_SkipsLoadedBoundaries() { - - var topic = await _topicRepository.Load(11111); - var rawTopic = (ITopicLazyLoadable)topic!; - - topic!.Attributes.LoadState = LoadState.NotLoaded; - Assert.True(rawTopic.IsLoaded(TopicPayload.Children)); - await rawTopic.EnsureLoaded(TopicPayload.Children | TopicPayload.ExtendedAttributes); - - Assert.True(rawTopic.IsLoaded(TopicPayload.ExtendedAttributes)); - Assert.True(rawTopic.IsLoaded(TopicPayload.Children)); - - } - - /*============================================================================================================================ - | TEST: IS LOADED: RELATIONSHIPS LOADED STATE: DOES NOT CALL RESOLVER - \---------------------------------------------------------------------------------------------------------------------------*/ - /// - /// Loads a whose is already and - /// accesses the getter. Verifies that the boundary stays without the resolver being called - /// redundantly. - /// - [Fact] - public async Task IsLoaded_RelationshipsLoadedState_DoesNotCallResolver() { - - var topic = await _topicRepository.Load(11111); - var rawTopic = (ITopicLazyLoadable)topic!; - - Assert.True(rawTopic.IsLoaded(TopicPayload.Relationships)); - _ = topic.Relationships; - - Assert.True(rawTopic.IsLoaded(TopicPayload.Relationships)); - - } - - /*============================================================================================================================ - | TEST: IS LOADED: REFERENCES LOADED STATE: DOES NOT CALL RESOLVER - \---------------------------------------------------------------------------------------------------------------------------*/ - /// - /// Loads a whose is already and accesses - /// the getter. Verifies that the boundary stays without the resolver being called - /// redundantly. - /// - [Fact] - public async Task IsLoaded_ReferencesLoadedState_DoesNotCallResolver() { - - var topic = await _topicRepository.Load(11111); - var rawTopic = (ITopicLazyLoadable)topic!; - - Assert.True(rawTopic.IsLoaded(TopicPayload.References)); - _ = topic.References; - - Assert.True(rawTopic.IsLoaded(TopicPayload.References)); - - } - /*============================================================================================================================ | TEST: MOVE: TOPIC MOVED EVENT: IS RAISED \---------------------------------------------------------------------------------------------------------------------------*/ @@ -1305,55 +1240,6 @@ public async Task Move_TopicMovedEvent_IsRaised() { } - /*============================================================================================================================ - | TEST: ENSURE LOADED: WITH MISSING RELATIONSHIP TARGET: RESOLVES AND CONNECTS - \---------------------------------------------------------------------------------------------------------------------------*/ - /// - /// Calls on a topic whose Relationships.LoadState is NotLoaded - /// , confirming that the resolver re-queries for the topic's relationships, loads any missing targets, and connects the - /// edges. - /// - /// - /// The stub pre-seeds a relationship from the root topic to Root:Web (id 10000). The cache is initialized with only the - /// root topic, so the relationship target is initially absent. EnsureLoaded is expected to load it and connect the - /// edge through the full resolver stack. - /// - [Fact] - public async Task EnsureLoaded_WithMissingRelationshipTarget_ResolvesAndConnects() { - - // Get the root topic from cache; seed a deferred entry to simulate a pending relationship target - var source = (await _cachedTopicRepository.Load(-1))!; - source.Relationships.Deferred.Add(new("_stub", 11111)); - - // Act: EnsureLoaded re-queries, finds the missing target, loads it, and connects the edge - await _cachedTopicRepository.EnsureLoaded(source, TopicPayload.Relationships); - - // Relationships are now Loaded and any pre-seeded edges are connected - Assert.Equal(LoadState.Loaded, source.Relationships.LoadState); - - } - - /*============================================================================================================================ - | TEST: ENSURE LOADED: RELATIONSHIPS: ALREADY LOADED: SKIPS FILL - \---------------------------------------------------------------------------------------------------------------------------*/ - /// - /// Calls on a topic whose relationships are already and confirms it returns immediately without re-querying. - /// - [Fact] - public async Task EnsureLoaded_Relationships_AlreadyLoaded_SkipsFill() { - - // Get the root topic; relationships start as Loaded (Deferred is empty) after initialization - var source = (await _cachedTopicRepository.Load(-1))!; - - // Act - await _cachedTopicRepository.EnsureLoaded(source, TopicPayload.Relationships); - - // LoadState is unchanged; no fill was triggered - Assert.Equal(LoadState.Loaded, source.Relationships.LoadState); - - } - /*============================================================================================================================ | TEST: MOVE: SAME LOCATION: EVENT NOT RAISED \---------------------------------------------------------------------------------------------------------------------------*/ From 951eba05ab7949658ce3d0150bc73a59f4518457 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Mon, 27 Jul 2026 20:03:02 -0700 Subject: [PATCH 257/337] Fixed `BaseTopic` lazy-loading bug Calls to set the `BaseTopic` weren't properly using the `ITopicBackingAccessor` (a9035bb8, e1b28c73), which didn't result in an error, but caused the `Topic.References` to call `EnsureLoaded()` twice: Once for setting the value, then for reading the value immediately after due to how it's called from `TopicPropertyDispatcher.Enforce()` while in the middle of a call to `TrackedRecordCollection.InsertItem()`. This was a sloppy miss on my side when implementing the backing fields needed for the lazy-loading infrastructure (#111). --- OnTopic/Topic.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/OnTopic/Topic.cs b/OnTopic/Topic.cs index 5a69478a..8f0da829 100644 --- a/OnTopic/Topic.cs +++ b/OnTopic/Topic.cs @@ -690,7 +690,7 @@ public Topic? BaseTopic { value != this, "A topic may not derive from itself." ); - References.SetValue("BaseTopic", value); + _references.SetValue("BaseTopic", value); } } From 2875725d12d5f4ef28f26eee7f8bfecdb634ecd4 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Mon, 27 Jul 2026 20:21:04 -0700 Subject: [PATCH 258/337] Establish stub to test concurrency issues This will setup concurrency issues so that we can test fixes to potential concurrency traps established by the lazy-loading infrastructure (#111), thus laying the foundation for the concurrency updates (#117). --- .../BlockingStubLazyLoadingTopicRepository.cs | 70 +++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 OnTopic.Tests/TestDoubles/BlockingStubLazyLoadingTopicRepository.cs diff --git a/OnTopic.Tests/TestDoubles/BlockingStubLazyLoadingTopicRepository.cs b/OnTopic.Tests/TestDoubles/BlockingStubLazyLoadingTopicRepository.cs new file mode 100644 index 00000000..ca8efa42 --- /dev/null +++ b/OnTopic.Tests/TestDoubles/BlockingStubLazyLoadingTopicRepository.cs @@ -0,0 +1,70 @@ +/*============================================================================================================================== +| Author Ignia, LLC +| Client Ignia, LLC +| Project Topics Library +\=============================================================================================================================*/ +using OnTopic.Repositories; +using OnTopic.TestDoubles.LazyLoading; + +namespace OnTopic.Tests.TestDoubles; + +/*============================================================================================================================== +| CLASS: BLOCKING STUB LAZY LOADING TOPIC REPOSITORY +\-----------------------------------------------------------------------------------------------------------------------------*/ +/// +/// A that counts every call and, while "armed", +/// suspends inside it until released, thus letting a test provably interleave two concurrent lazy loads of the same topic +/// without or other timing hacks. +/// +[ExcludeFromCodeCoverage] +internal sealed class BlockingStubLazyLoadingTopicRepository: StubLazyLoadingTopicRepository { + + /*============================================================================================================================ + | PRIVATE FIELDS + \---------------------------------------------------------------------------------------------------------------------------*/ + private TaskCompletionSource? _gate; + + /*============================================================================================================================ + | PROPERTY: FETCH COUNT + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Returns the number of times has been called. + /// + public int FetchCount { get; private set; } + + /*============================================================================================================================ + | METHOD: ARM GATE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// "Arms" the gate so the next call suspends until is called. + /// + public void ArmGate() => _gate = new(TaskCreationOptions.RunContinuationsAsynchronously); + + /*============================================================================================================================ + | METHOD: RELEASE GATE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Releases a suspended call "armed" via . + /// + public void ReleaseGate() => _gate?.SetResult(); + + /*============================================================================================================================ + | METHODS: TOPIC LAZY LOADER + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + public override async Task EnsureLoaded(Topic topic, TopicPayload payload, CancellationToken cancellationToken = default) { + + // Record the fetch + FetchCount++; + + // If "armed", suspend until released + if (_gate is not null) { + await _gate.Task.ConfigureAwait(false); + } + + // Delegate to the base implementation to perform the actual fill + await base.EnsureLoaded(topic, payload, cancellationToken).ConfigureAwait(false); + + } + +} //Class \ No newline at end of file From 14fb36e55f31792d6bb9f1909e5f83b3358b0036 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Mon, 27 Jul 2026 20:33:34 -0700 Subject: [PATCH 259/337] Introduced concurrency unit test Building off of the new `BlockingStubLazyLoadingTopicRepository` (2875725d), introduced a new unit test to trigger concurrency and ensure that the data is not corrupted, thus laying the foundation for the concurrency updates (#117) that address potential issues introduced by the lazy-loading infrastructure (#111). --- OnTopic.Tests/CachedTopicRepositoryTest.cs | 47 +++++++++++++++++++++- 1 file changed, 46 insertions(+), 1 deletion(-) diff --git a/OnTopic.Tests/CachedTopicRepositoryTest.cs b/OnTopic.Tests/CachedTopicRepositoryTest.cs index 2c464ae1..5c929091 100644 --- a/OnTopic.Tests/CachedTopicRepositoryTest.cs +++ b/OnTopic.Tests/CachedTopicRepositoryTest.cs @@ -4,6 +4,7 @@ | Project Topics Library \=============================================================================================================================*/ using System.Data; +using OnTopic.Collections; using OnTopic.Collections.Specialized; using OnTopic.Data.Caching; using OnTopic.Data.Sql; @@ -185,7 +186,7 @@ public async Task Load_AfterAttachedButUnindexedSubtree_ReturnsAttachedInstance( /// arriving dangling. /// [Fact] - public async Task EnsureLoaded_DeferredAssociationFallbackWithResidentTargetParent_AttachesToCacheGraph() { + public async Task TaskEnsureLoaded_DeferredAssociationFallbackWithResidentTargetParent_AttachesToCacheGraph() { var inner = new FakeSqlTopicRepository() .AddTopic(1, "Root", "Container", null) @@ -217,6 +218,50 @@ public async Task EnsureLoaded_DeferredAssociationFallbackWithResidentTargetPare } + /*============================================================================================================================ + | TEST: ENSURE LOADED: CONCURRENT CHILDREN REQUESTS: FETCHES ONCE WITHOUT CORRUPTION + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Reproduces a concurrent-read race on a shared property: + /// Two concurrent requests for the same cached topic must merge exactly once, + /// not twice, into the shared . + /// + /// + /// Uses , which suspends inside its own EnsureLoaded until + /// released, to interleave both requests without any or other timing hack: The first + /// request is proven in flight because it is the one suspended on the gate; the second is proven in flight because calling + /// it synchronously (i.e., without ) before releasing the gate runs against to its own suspension + /// before the test proceeds. + /// + [Fact] + public async Task EnsureLoaded_ConcurrentChildrenRequests_FetchesOnceWithoutCorruption() { + + var inner = new BlockingStubLazyLoadingTopicRepository(); + var cache = new CachedTopicRepository(inner); + var web = await cache.Load("Web"); + var rawWeb = (ITopicLazyLoadable)web!; + + Assert.False(rawWeb.IsLoaded(TopicPayload.Children)); + + // "Arm" the gate so the first request suspends mid-fetch, then launch both requests without awaiting either + inner.ArmGate(); + + var firstRequest = rawWeb.EnsureLoaded(TopicPayload.Children, CancellationToken); + var secondRequest = rawWeb.EnsureLoaded(TopicPayload.Children, CancellationToken); + + // Release the gate and let both requests run to completion + inner.ReleaseGate(); + + await Task.WhenAll(firstRequest, secondRequest); + + // A single inner fetch, no duplicate children, and a fully loaded boundary confirm the race did not corrupt the merge + Assert.Equal(1, inner.FetchCount); + Assert.True(rawWeb.IsLoaded(TopicPayload.Children)); + Assert.Equal(2, web.Children.Count); + Assert.Equal(2, web.Children.Select(child => child.Id).Distinct().Count()); + + } + /*============================================================================================================================ | TEST: DELETE: LOADED TOPIC: SUBSEQUENT LOAD DOES NOT RETURN DETACHED INSTANCE \---------------------------------------------------------------------------------------------------------------------------*/ From 5779261835fb57bbd1d100c62bdcabe5758848f8 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Mon, 27 Jul 2026 21:04:13 -0700 Subject: [PATCH 260/337] Added `EnsureLoaded()` concurrency gate per topic While multiple topics can lazy load their members concurrently, `EnsureLoaded()` should only operate against a single topic at a time, thus avoiding potential concurrency issues or corrupted data. This rechecks the `TopicPayload` against the `LoadState` `FilterPayload()` after the gate is released to avoid retrieving the same data that a previous request just loaded. This provides the core fix for the concurrency updates (#117) to the lazy-loading infrastructure (#111). Associations will be handled in a subsequent commit. --- OnTopic.Data.Caching/CachedTopicRepository.cs | 42 ++++++++++++++++++- 1 file changed, 40 insertions(+), 2 deletions(-) diff --git a/OnTopic.Data.Caching/CachedTopicRepository.cs b/OnTopic.Data.Caching/CachedTopicRepository.cs index 929b5429..da781509 100644 --- a/OnTopic.Data.Caching/CachedTopicRepository.cs +++ b/OnTopic.Data.Caching/CachedTopicRepository.cs @@ -3,6 +3,7 @@ | Client Ignia, LLC | Project Topics Library \=============================================================================================================================*/ +using System.Collections.Concurrent; using OnTopic.Collections.Specialized; using OnTopic.Internal.Diagnostics; using OnTopic.Querying; @@ -31,6 +32,22 @@ public class CachedTopicRepository : TopicRepositoryDecorator, ITopicLazyLoader private readonly HashSet _absentTopicIdIndex = new(); private readonly HashSet _absentUniqueKeyIndex = new(StringComparer.OrdinalIgnoreCase); private readonly object _syncLock = new(); + private readonly ConcurrentDictionary _loadGates = new(); + + /*============================================================================================================================ + | CONSTANTS + \---------------------------------------------------------------------------------------------------------------------------*/ + + /// + /// Payload whose full load lets a per-topic gate be reclaimed. + /// + /// + /// This excludes , which rarely loads outside the editor, so most gates reclaim as + /// soon as and converge, rather than + /// persisting indefinitely. A gate recreated later for a -only fetch is reclaimed + /// immediately once that fetch completes. + /// + private const TopicPayload _reclaimPayload = TopicPayload.Children | TopicPayload.ExtendedAttributes; /*============================================================================================================================ | CONSTRUCTOR @@ -247,7 +264,8 @@ public virtual async Task EnsureLoaded(Topic topic, TopicPayload payload, Cancel /*-------------------------------------------------------------------------------------------------------------------------- | Filter to pending (i.e., not yet Loaded) payload \-------------------------------------------------------------------------------------------------------------------------*/ - payload = ((ITopicLazyLoadable)topic).FilterPayload(payload); + var rawTopic = (ITopicLazyLoadable)topic; + payload = rawTopic.FilterPayload(payload); if (payload is TopicPayload.None) { return; @@ -265,7 +283,27 @@ public virtual async Task EnsureLoaded(Topic topic, TopicPayload payload, Cancel if (TopicRepository is ITopicLazyLoader loader) { var innerPayload = payload & ~(TopicPayload.Relationships | TopicPayload.References); if (innerPayload is not TopicPayload.None) { - await loader.EnsureLoaded(topic, innerPayload, cancellationToken).ConfigureAwait(false); + + // Serialize fetches and merges (children, extended attributes, version history) per topic + var gate = _loadGates.GetOrAdd(topic.Id, _ => new(1, 1)); + await gate.WaitAsync(cancellationToken).ConfigureAwait(false); + try { + + // Second escape hatch: Re-filter under the gate, since a prior holder may have merged some or all of this payload + innerPayload = rawTopic.FilterPayload(innerPayload); + if (innerPayload is not TopicPayload.None) { + await loader.EnsureLoaded(topic, innerPayload, cancellationToken).ConfigureAwait(false); + } + } + finally { + gate.Release(); + } + + // Reclaim: Once ReclaimPayload is loaded, the gate is dead weight, so we can drop the cached instance + if (rawTopic.IsLoaded(_reclaimPayload)) { + _loadGates.TryRemove(new(topic.Id, gate)); + } + } } From f09a43a19bcb989b00c8a2982d519e4856cc3692 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Mon, 27 Jul 2026 21:58:09 -0700 Subject: [PATCH 261/337] Updated `Load()` to take `depth` not `isRecursive` Instead of passing a `bool` for `isRecursive` on `Load()`, now take a `depth` instead, which allows -1 (for `isRecursive`), 0 (for the topicId specified only), or _n_ (to load _n_ tiers from the hierarchy, useful for e.g., preloading the navigation). It also moves it to the third argument, after `TopicPayload` (58524089). For now, this is normalized to the legacy `@LoadChildren` (9c91f295) and `@LoadDescendants` (8c2c81da) in the `GetTopics` stored procedure. In subsequent updates, those will be replaced with a true, first-party `@depth` parameter. This is a major break in the signature, but that corresponds to adding `TopicPayload` (58524089) and making `Load()` asynchronous (a3b73602), and is slated for the major 6.0.0 release alongside other breaking changes, so the impact is already baked in. This is the primary interface change for the depth-limited `Load()` task (#120). --- .../TopicRepositoryExtensions.cs | 4 +- OnTopic.Data.Caching/CachedTopicRepository.cs | 57 ++++++++++--------- OnTopic.Data.Sql/SqlTopicRepository.cs | 33 +++++++---- OnTopic/Collections/ChildTopicCollection.cs | 2 +- .../Specialized/TrackedRecord{T}.cs | 2 +- OnTopic/Repositories/ITopicRepository.cs | 45 ++++++++------- .../LazyLoadingTopicRepository.cs | 8 +-- .../Repositories/ObservableTopicRepository.cs | 12 ++-- .../Repositories/TopicRepositoryDecorator.cs | 12 ++-- .../_eventArgs/TopicLoadEventArgs.cs | 2 +- 10 files changed, 98 insertions(+), 79 deletions(-) diff --git a/OnTopic.AspNetCore.Mvc/TopicRepositoryExtensions.cs b/OnTopic.AspNetCore.Mvc/TopicRepositoryExtensions.cs index ef17fb92..01c5114a 100644 --- a/OnTopic.AspNetCore.Mvc/TopicRepositoryExtensions.cs +++ b/OnTopic.AspNetCore.Mvc/TopicRepositoryExtensions.cs @@ -27,8 +27,8 @@ public static class TopicRepositoryExtensions { /// of the box routes, such as controller and action, the defines /// additional topic-specific routes, such as rootTopic and path. These can be combined to identify a topic /// in the repository. By using the extension method, callers needn't assemble their own - /// prior to calling , assuming they are using the standard routing - /// variables. + /// prior to calling , assuming they are using the + /// standard routing variables. /// public static Topic? Load( this ITopicRepository topicRepository, diff --git a/OnTopic.Data.Caching/CachedTopicRepository.cs b/OnTopic.Data.Caching/CachedTopicRepository.cs index da781509..b80c623a 100644 --- a/OnTopic.Data.Caching/CachedTopicRepository.cs +++ b/OnTopic.Data.Caching/CachedTopicRepository.cs @@ -71,7 +71,7 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos | deferred, preserving the benefits of lazy loading below this boundary. \-------------------------------------------------------------------------------------------------------------------------*/ var rootTopic = TopicRepository - .Load("Root", referenceTopic: null, isRecursive: false, payload: TopicPayload.All) + .Load("Root", referenceTopic: null, payload: TopicPayload.All) .GetAwaiter() .GetResult(); @@ -90,7 +90,7 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos | Eager-load Root:Configuration subtree (required for content-type descriptor resolution) \-------------------------------------------------------------------------------------------------------------------------*/ TopicRepository - .Load("Root:Configuration", referenceTopic: _cache, isRecursive: true, payload: TopicPayload.All) + .Load("Root:Configuration", referenceTopic: _cache, payload: TopicPayload.All, depth: -1) .GetAwaiter() .GetResult(); @@ -112,8 +112,8 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos \---------------------------------------------------------------------------------------------------------------------------*/ /// /// - /// Returns a cached topic if it satisfies the requested and ; an - /// insufficient hit is topped up via before being returned. On a + /// Returns a cached topic if it satisfies the requested and ; an + /// insufficient hit is topped up via before being returned. On a /// miss, falls through to the underlying repository with @LoadAscendants enabled so the full ancestor chain is /// fetched and merged into the live graph, using if supplied, or the cache root /// otherwise, so the underlying load seeds its working index from, and can attach directly to, the resident graph. Missing @@ -122,15 +122,15 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos public override async Task Load( int topicId, Topic? referenceTopic = null, - bool isRecursive = false, - TopicPayload payload = TopicPayload.None + TopicPayload payload = TopicPayload.None, + int depth = 0 ) { /*-------------------------------------------------------------------------------------------------------------------------- | Handle request for entire tree \-------------------------------------------------------------------------------------------------------------------------*/ if (topicId < 0) { - await EnsureLoaded(_cache, payload, isRecursive).ConfigureAwait(false); + await EnsureLoaded(_cache, payload, depth).ConfigureAwait(false); return _cache; } @@ -139,7 +139,7 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos \-------------------------------------------------------------------------------------------------------------------------*/ _cache.GetLiveTopicIndex().TryGetValue(topicId, out var topic); if (topic is not null) { - await EnsureLoaded(topic, payload, isRecursive).ConfigureAwait(false); + await EnsureLoaded(topic, payload, depth).ConfigureAwait(false); return topic; } @@ -156,7 +156,7 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos | On miss: Load with ancestors and merge result into the live graph \-------------------------------------------------------------------------------------------------------------------------*/ var loaded = await TopicRepository - .Load(topicId, referenceTopic?? _cache, isRecursive, payload) + .Load(topicId, referenceTopic?? _cache, payload, depth) .ConfigureAwait(false); // If it's missing, populate the appropriate index so we don't try loading it again @@ -175,8 +175,8 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos /// /// - /// Returns a cached topic if it satisfies the requested and ; an - /// insufficient hit is topped up via before being returned. On a + /// Returns a cached topic if it satisfies the requested and ; an + /// insufficient hit is topped up via before being returned. On a /// miss, falls through to the underlying repository with @LoadAscendants enabled so the full ancestor chain is /// fetched and merged into the live graph, using if supplied, or the cache root /// otherwise, so the underlying load seeds its working index from, and can attach directly to, the resident graph. Missing @@ -185,8 +185,8 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos public override async Task Load( string uniqueKey, Topic? referenceTopic = null, - bool isRecursive = false, - TopicPayload payload = TopicPayload.None + TopicPayload payload = TopicPayload.None, + int depth = 0 ) { /*-------------------------------------------------------------------------------------------------------------------------- @@ -214,7 +214,7 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos _topicKeyIndex.TryGetValue(uniqueKey, out resident); } if (resident is not null) { - await EnsureLoaded(resident, payload, isRecursive).ConfigureAwait(false); + await EnsureLoaded(resident, payload, depth).ConfigureAwait(false); return resident; } @@ -231,7 +231,7 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos | On miss: Load with ancestors and merge result into the live graph \-------------------------------------------------------------------------------------------------------------------------*/ var loaded = await TopicRepository - .Load(uniqueKey, referenceTopic?? _cache, isRecursive, payload) + .Load(uniqueKey, referenceTopic?? _cache, payload, depth) .ConfigureAwait(false); if (loaded is null) { @@ -322,7 +322,7 @@ public virtual async Task EnsureLoaded(Topic topic, TopicPayload payload, Cancel /// /// Adds the newly loaded topic to the index and clears any entries previously known to be missing, so a topic that was /// missing on an earlier lookup can be found now. This automatically indexes any descendants loaded alongside the topic, - /// for cases where the isRecursive parameter was specified on . + /// for cases where a non-zero depth was specified on . /// Ancestors pulled in via @LoadAscendants sit above the topic, so , /// which only walks downward, never reaches them; they are indexed by walking up the parent chain instead. /// @@ -508,7 +508,7 @@ private void RekeyTopicSubtree(Topic topic, string oldRootUniqueKey) { \---------------------------------------------------------------------------------------------------------------------------*/ /// /// Confirms that already satisfies the requested and scope and, if not, tops it up in place; the caller's own reference to reflects + /// "depth"/> scope and, if not, tops it up in place; the caller's own reference to reflects /// whatever is added. /// /// @@ -518,40 +518,45 @@ private void RekeyTopicSubtree(Topic topic, string oldRootUniqueKey) { /// /// /// A single-topic shortfall is topped up via , which converges LoadState in a single batched round-trip. A recursive shortfall, including a whole-tree - /// request, performs one deep against the + /// />, which converges LoadState in a single batched round-trip. Any other shortfall, including a whole-tree + /// request, performs one deep against the /// underlying repository, using itself as the reference into the topic graph, so the underlying /// load merges the result directly into it. It then looks up any in-graph associations (), so any relationship or reference targets /// that just became resident are connected without a further trip. /// + /// + /// Interim gate semantics (Stage 1): is only distinguished from zero here—any non-zero value is + /// treated as the old isRecursive: true, a documented superset until Stage 3 tightens the gate to honor the + /// requested depth precisely. + /// /// /// The already-resident topic to confirm or top up. /// The flags the caller requires to be loaded. - /// Whether the caller requires the full subtree, not merely itself. + /// The number of tiers of descendants the caller requires, not merely itself. private async Task EnsureLoaded( Topic topic, TopicPayload payload, - bool isRecursive + int depth ) { // Narrow the sufficiency gate to exclude relationships and references, which Load() never guarantees are fully resolved var gate = payload & ~(TopicPayload.Relationships | TopicPayload.References); // Return immediately if the resident topic already satisfies the requested scope - if (((ITopicLazyLoadable)topic).IsLoaded(gate, isRecursive)) { + if (((ITopicLazyLoadable)topic).IsLoaded(gate, depth != 0)) { return; } - // Top up a non-recursive shortfall via the loader, which converges LoadState in a single round-trip - if (!isRecursive) { + // Top up a single-topic shortfall via the loader, which converges LoadState in a single round-trip + if (depth is 0) { await ((ITopicLazyLoadable)topic).EnsureLoaded(gate).ConfigureAwait(false); return; } - // Top up a recursive shortfall via one deep load, merged into the live graph + // Top up any other shortfall via one deep load, merged into the live graph var loaded = await TopicRepository - .Load(topic.Id, topic, isRecursive, payload) + .Load(topic.Id, topic, payload, depth) .ConfigureAwait(false); if (loaded is not null) { diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index a6bd6a9c..e7ab68bd 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -58,8 +58,8 @@ public SqlTopicRepository(string connectionString) { public override async Task Load( string uniqueKey, Topic? referenceTopic = null, - bool isRecursive = false, - TopicPayload payload = TopicPayload.None + TopicPayload payload = TopicPayload.None, + int depth = 0 ) { /*-------------------------------------------------------------------------------------------------------------------------- @@ -113,7 +113,7 @@ public SqlTopicRepository(string connectionString) { /*-------------------------------------------------------------------------------------------------------------------------- | Return topic \-------------------------------------------------------------------------------------------------------------------------*/ - return await Load(topicId, referenceTopic, isRecursive, payload).ConfigureAwait(false); + return await Load(topicId, referenceTopic, payload, depth).ConfigureAwait(false); } @@ -121,10 +121,17 @@ public SqlTopicRepository(string connectionString) { public override async Task Load( int topicId, Topic? referenceTopic = null, - bool isRecursive = false, - TopicPayload payload = TopicPayload.None + TopicPayload payload = TopicPayload.None, + int depth = 0 ) { + /*-------------------------------------------------------------------------------------------------------------------------- + | Normalize depth + \-------------------------------------------------------------------------------------------------------------------------*/ + if (payload.HasFlag(TopicPayload.Children) && depth is 0) { + depth = 1; + } + /*-------------------------------------------------------------------------------------------------------------------------- | Establish database connection \-------------------------------------------------------------------------------------------------------------------------*/ @@ -138,10 +145,14 @@ public SqlTopicRepository(string connectionString) { /*-------------------------------------------------------------------------------------------------------------------------- | Establish query parameters + >------------------------------------------------------------------------------------------------------------------------- + | Interim mapping of depth onto GetTopics' boolean parameters until a depth-aware @Depth parameter: -1 loads the full + | subtree; 1 loads one tier of children; 0 loads neither; N ≥ 2 is a documented superset that over-fetches the full subtree + | until @Depth is wired up. \-------------------------------------------------------------------------------------------------------------------------*/ command.AddParameter("TopicID", topicId); - command.AddParameter("LoadDescendants", isRecursive); - command.AddParameter("LoadChildren", payload.HasFlag(TopicPayload.Children) && !isRecursive); + command.AddParameter("LoadDescendants", depth is (-1) or >= 2); + command.AddParameter("LoadChildren", depth is 1); command.AddParameter("LoadAscendants", topicId >= 0); command.AddParameter("IncludeExtended", payload.HasFlag(TopicPayload.ExtendedAttributes)); command.AddParameter("IncludeRelationships", true); @@ -189,7 +200,7 @@ public SqlTopicRepository(string connectionString) { /*-------------------------------------------------------------------------------------------------------------------------- | Raise event \-------------------------------------------------------------------------------------------------------------------------*/ - OnTopicLoaded(new(topic, isRecursive)); + OnTopicLoaded(new(topic, depth < 0)); /*-------------------------------------------------------------------------------------------------------------------------- | Return objects @@ -269,7 +280,7 @@ public SqlTopicRepository(string connectionString) { /*-------------------------------------------------------------------------------------------------------------------------- | Raise event \-------------------------------------------------------------------------------------------------------------------------*/ - OnTopicLoaded(new(topic, false, version)); + OnTopicLoaded(new(topic, 0, version)); /*-------------------------------------------------------------------------------------------------------------------------- | Return objects @@ -460,7 +471,7 @@ public virtual async Task EnsureLoaded(Topic topic, TopicPayload payload, Cancel \-------------------------------------------------------------------------------------------------------------------------*/ if (payload.HasFlag(TopicPayload.Children)) { foreach (var child in topic.Children) { - OnTopicLoaded(new(child, isRecursive: false)); + OnTopicLoaded(new(child, depth: 0)); } } @@ -777,7 +788,7 @@ protected override sealed async Task DeleteTopic(Topic topic) { /// /// /// Indexed attributes and associations are only requested when filling the boundary, - /// as they are otherwise always loaded as part of the initial for + /// as they are otherwise always loaded as part of the initial for /// existing topics. /// private static void AddEnsureLoadedParameters(SqlCommand command, int topicId, TopicPayload payload) { diff --git a/OnTopic/Collections/ChildTopicCollection.cs b/OnTopic/Collections/ChildTopicCollection.cs index aa5409ae..10d6cba5 100644 --- a/OnTopic/Collections/ChildTopicCollection.cs +++ b/OnTopic/Collections/ChildTopicCollection.cs @@ -54,7 +54,7 @@ internal ChildTopicCollection(Topic parent) { /// /// /// This setter exists for implementations populating or converging load state during or . + /// cref="ITopicRepository.Load(Int32, Topic?, TopicPayload, int)"/> or . /// Setting while children remain unfetched masks the deferral from subsequent readers; /// setting on already-resident children induces a spurious synchronous load on /// next access. diff --git a/OnTopic/Collections/Specialized/TrackedRecord{T}.cs b/OnTopic/Collections/Specialized/TrackedRecord{T}.cs index 0c3f8f37..d896fd78 100644 --- a/OnTopic/Collections/Specialized/TrackedRecord{T}.cs +++ b/OnTopic/Collections/Specialized/TrackedRecord{T}.cs @@ -102,7 +102,7 @@ protected TrackedRecord(string key, T? value, bool isDirty = true, DateTime? las /// Gets the for the given item. /// /// - /// If loaded from a data store from e.g. , the + /// If loaded from a data store from e.g. , the /// should be set to the Version. If the is novel, however, then it /// should be set to the current date. That won't be the same date established by for the Version, however, which is why this property is labeled /// Raised after a is loaded from the as part of a operation, or one of its overloads. + /// "ITopicRepository.Load(String, Topic?, TopicPayload, Int32)"/> operation, or one of its overloads. /// /// /// @@ -90,59 +90,62 @@ public interface ITopicRepository { \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Loads the root , using the same lazy defaults as . + /// Loads the root , using the same lazy defaults as . /// /// A topic object. public Task Load() => Load(-1); /// - /// Loads a (and, optionally, all of its descendants) based on the specified . + /// Loads a (and, optionally, some or all of its descendants) based on the specified . /// /// The topic identifier. /// /// When loading a single topic or branch, offers a reference topic graph that can be used to ensure that topic /// associations—such as references, relationships, and —are integrated with existing entities. /// - /// - /// Whether to load the full descendant subtree rooted at the seed topic. When , only the seed topic - /// itself is loaded. Ancestor topics are always loaded when needed to place the seed topic within the graph. - /// /// Specifies which data to include with each topic. + /// + /// The number of tiers of descendants to load below the seed topic. -1 loads the full subtree; 0 loads only + /// the seed topic; N loads N tiers of descendants. Ancestor topics are always loaded when needed to place + /// the seed topic within the graph. + /// /// A topic object. Task Load( int topicId, Topic? referenceTopic = null, - bool isRecursive = false, - TopicPayload payload = TopicPayload.None + TopicPayload payload = TopicPayload.None, + int depth = 0 ); /// - /// Loads a (and, optionally, all of its descendants) based on a specified . + /// Loads a (and, optionally, some or all of its descendants) based on a specified . /// /// The fully-qualified unique topic key. /// /// When loading a single topic or branch, offers a reference topic graph that can be used to ensure that topic /// associations—such as references, relationships, and —are integrated with existing entities. /// - /// - /// Whether to load the full descendant subtree. See for details. - /// /// - /// Specifies which data to include with each topic. See + /// Specifies which data to include with each topic. See /// for details. /// + /// + /// The number of tiers of descendants to load. See for details. + /// /// A topic object. Task Load( string uniqueKey, Topic? referenceTopic = null, - bool isRecursive = false, - TopicPayload payload = TopicPayload.None + TopicPayload payload = TopicPayload.None, + int depth = 0 ); - /// + /// [ExcludeFromCodeCoverage] - [Obsolete("This overload has been removed in preference for Load(string, Topic, Boolean).")] + [Obsolete("This overload has been removed in preference for Load(string, Topic, TopicPayload, int).")] Task Load(string? uniqueKey, bool isRecursive); /// @@ -195,7 +198,7 @@ public interface ITopicRepository { /// Unlike or , this mutates /// in place, immediately followed by . It is not appropriate for /// previewing a historical version; use for that, as it only load the version, without - /// incporating it into any in-memory topic graph or committing the previous version to the persistence store. + /// incorporating it into any in-memory topic graph or committing the previous version to the persistence store. /// /// The current version of the to rollback. /// The selected Date/Time for the version to which to roll back. @@ -263,7 +266,7 @@ public interface ITopicRepository { /// exception="T:System.ArgumentNullException"> /// topic is not null /// - Task Move(Topic topic, Topic target, Topic? sibling = null); + Task Move(Topic topic, Topic target, Topic? sibling = null); /*============================================================================================================================ | METHOD: DELETE diff --git a/OnTopic/Repositories/LazyLoadingTopicRepository.cs b/OnTopic/Repositories/LazyLoadingTopicRepository.cs index 9b7e7fa6..265e6d4c 100644 --- a/OnTopic/Repositories/LazyLoadingTopicRepository.cs +++ b/OnTopic/Repositories/LazyLoadingTopicRepository.cs @@ -72,8 +72,8 @@ protected override void OnTopicSaved(TopicSaveEventArgs args) { \---------------------------------------------------------------------------------------------------------------------------*/ /// /// Resolves any relationships and references that were deferred when loaded through this repository's , preferring whatever is already available in the topic's - /// graph before falling back to a fresh for any + /// "ITopicRepository.Load(Int32, Topic?, TopicPayload, Int32)"/>, preferring whatever is already available in the topic's + /// graph before falling back to a fresh for any /// that aren't. /// /// @@ -116,7 +116,7 @@ protected Task ResolveAssociations(Topic topic, TopicPayload payload) { /// /// Resolves each deferred relationship and reference entry on against its resident graph, - /// optionally falling back to for whatever the + /// optionally falling back to for whatever the /// graph doesn't have. /// /// @@ -136,7 +136,7 @@ protected Task ResolveAssociations(Topic topic, TopicPayload payload) { /// /// /// Whether an association missing from the graph should be fetched via , with whatever remains unresolved afterwards cleared as + /// "ITopicRepository.Load(Int32, Topic?, TopicPayload, Int32)"/>, with whatever remains unresolved afterwards cleared as /// stale. /// private async Task ResolveAssociations(Topic topic, TopicPayload payload, bool fallBackToLoad) { diff --git a/OnTopic/Repositories/ObservableTopicRepository.cs b/OnTopic/Repositories/ObservableTopicRepository.cs index 47f2b21c..16ce5ce5 100644 --- a/OnTopic/Repositories/ObservableTopicRepository.cs +++ b/OnTopic/Repositories/ObservableTopicRepository.cs @@ -215,21 +215,21 @@ public event EventHandler? TopicRenamed { public abstract Task Load( int topicId, Topic? referenceTopic = null, - bool isRecursive = false, - TopicPayload payload = TopicPayload.None + TopicPayload payload = TopicPayload.None, + int depth = 0 ); /// public abstract Task Load( string uniqueKey, Topic? referenceTopic = null, - bool isRecursive = false, - TopicPayload payload = TopicPayload.None + TopicPayload payload = TopicPayload.None, + int depth = 0 ); - /// + /// [ExcludeFromCodeCoverage] - [Obsolete("This overload has been removed in preference for Load(string, Topic, Boolean).")] + [Obsolete("This overload has been removed in preference for Load(string, Topic, TopicPayload, int).")] public Task Load(string? uniqueKey, bool isRecursive) => throw new NotImplementedException(); /// diff --git a/OnTopic/Repositories/TopicRepositoryDecorator.cs b/OnTopic/Repositories/TopicRepositoryDecorator.cs index 4fc6f45d..2de3c867 100644 --- a/OnTopic/Repositories/TopicRepositoryDecorator.cs +++ b/OnTopic/Repositories/TopicRepositoryDecorator.cs @@ -83,19 +83,19 @@ protected TopicRepositoryDecorator(ITopicRepository topicRepository) { public override Task Load( int topicId, Topic? referenceTopic = null, - bool isRecursive = false, - TopicPayload payload = TopicPayload.None + TopicPayload payload = TopicPayload.None, + int depth = 0 ) => - TopicRepository.Load(topicId, referenceTopic, isRecursive, payload); + TopicRepository.Load(topicId, referenceTopic, payload, depth); /// public override Task Load( string uniqueKey, Topic? referenceTopic = null, - bool isRecursive = false, - TopicPayload payload = TopicPayload.None + TopicPayload payload = TopicPayload.None, + int depth = 0 ) => - TopicRepository.Load(uniqueKey, referenceTopic, isRecursive, payload); + TopicRepository.Load(uniqueKey, referenceTopic, payload, depth); /// public override Task Load(Topic topic, DateTime version) diff --git a/OnTopic/Repositories/_eventArgs/TopicLoadEventArgs.cs b/OnTopic/Repositories/_eventArgs/TopicLoadEventArgs.cs index 8dead99e..f330b27d 100644 --- a/OnTopic/Repositories/_eventArgs/TopicLoadEventArgs.cs +++ b/OnTopic/Repositories/_eventArgs/TopicLoadEventArgs.cs @@ -19,7 +19,7 @@ public class TopicLoadEventArgs : TopicEventArgs { \---------------------------------------------------------------------------------------------------------------------------*/ /// /// The object defines the event arguments relevant to a operation and its overloads. + /// Load(Int32, Topic?, TopicPayload, Int32)"/> operation and its overloads. /// /// The object associated with the rename event. /// Whether or not descendants of the were also loaded. From 28a943171c9b6459a7f216335927763f73546fbf Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Mon, 27 Jul 2026 22:02:20 -0700 Subject: [PATCH 262/337] Added `Depth` to `TopicLoadEventArgs` It appears that `IsRecursive` was never actually wired up as a property for `TopicLoadEventArgs`, despite being represented as an `isRecursive` parameter. Nevertheless, it can now be replaced with `Depth`, matching the corresponding update to the `Load()` signature (f09a43a1). This contributes to the depth-limited `Load()` task (#120). --- OnTopic.Data.Sql/SqlTopicRepository.cs | 2 +- .../_eventArgs/TopicLoadEventArgs.cs | 17 +++++++++++++++-- 2 files changed, 16 insertions(+), 3 deletions(-) diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index e7ab68bd..4dd7b969 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -200,7 +200,7 @@ public SqlTopicRepository(string connectionString) { /*-------------------------------------------------------------------------------------------------------------------------- | Raise event \-------------------------------------------------------------------------------------------------------------------------*/ - OnTopicLoaded(new(topic, depth < 0)); + OnTopicLoaded(new(topic, depth)); /*-------------------------------------------------------------------------------------------------------------------------- | Return objects diff --git a/OnTopic/Repositories/_eventArgs/TopicLoadEventArgs.cs b/OnTopic/Repositories/_eventArgs/TopicLoadEventArgs.cs index f330b27d..8d92d009 100644 --- a/OnTopic/Repositories/_eventArgs/TopicLoadEventArgs.cs +++ b/OnTopic/Repositories/_eventArgs/TopicLoadEventArgs.cs @@ -22,17 +22,30 @@ public class TopicLoadEventArgs : TopicEventArgs { /// Load(Int32, Topic?, TopicPayload, Int32)"/> operation and its overloads. /// /// The object associated with the rename event. - /// Whether or not descendants of the were also loaded. + /// The number of tiers of descendants that were also loaded. See for details. /// If a specific version was loaded, specified that version. - public TopicLoadEventArgs(Topic topic, bool isRecursive, DateTime? version = null): base(topic, isRecursive) { + public TopicLoadEventArgs(Topic topic, int depth, DateTime? version = null): base(topic, depth != 0) { /*-------------------------------------------------------------------------------------------------------------------------- | Initialize properties \-------------------------------------------------------------------------------------------------------------------------*/ + Depth = depth; Version = version; } + /*============================================================================================================================ + | PROPERTY: DEPTH + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Gets or sets the number of tiers of descendants that were loaded below the . + /// + /// + /// -1 indicates the full subtree was loaded; 0 indicates only the seed + /// itself was loaded; N indicates N tiers of descendants were loaded. + /// + public int Depth { get; set; } + /*============================================================================================================================ | PROPERTY: VERSION \---------------------------------------------------------------------------------------------------------------------------*/ From d3706048db0a5e32d0985118a202d88254d726d4 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Mon, 27 Jul 2026 22:22:08 -0700 Subject: [PATCH 263/337] Updated `IsLoaded()` to take `depth` Updated `IsLoaded()` to take `depth` instead of `isRecursive`, mirroring the corresponding signature change to its current consumer, `Load()` (f09a43a1). This also required the unit tests for `ITopicLazyLoadable` that called `IsLoaded()` to be updated. In subsequent tasks, we'll add additional tests to evaluate the _n_ depth case, which doesn't translate from the current implementation that was originally based on a bool. This contributes to the depth-limited `Load()` task (#120). --- OnTopic.Data.Caching/CachedTopicRepository.cs | 8 +++--- OnTopic.Tests/ITopicLazyLoadableTest.cs | 26 +++++++++---------- OnTopic/Repositories/ITopicLazyLoadable.cs | 18 +++++++------ 3 files changed, 27 insertions(+), 25 deletions(-) diff --git a/OnTopic.Data.Caching/CachedTopicRepository.cs b/OnTopic.Data.Caching/CachedTopicRepository.cs index b80c623a..8f99e9fd 100644 --- a/OnTopic.Data.Caching/CachedTopicRepository.cs +++ b/OnTopic.Data.Caching/CachedTopicRepository.cs @@ -526,9 +526,9 @@ private void RekeyTopicSubtree(Topic topic, string oldRootUniqueKey) { /// that just became resident are connected without a further trip. /// /// - /// Interim gate semantics (Stage 1): is only distinguished from zero here—any non-zero value is - /// treated as the old isRecursive: true, a documented superset until Stage 3 tightens the gate to honor the - /// requested depth precisely. + /// Interim top-up cost (Stage 1): the gate itself honors precisely, but the underlying still over-fetches a full subtree for any depth + /// ≥ 2 shortfall until Stage 2 wires up a depth-bounded SQL fetch—correct results, interim cost only. /// /// /// The already-resident topic to confirm or top up. @@ -544,7 +544,7 @@ int depth var gate = payload & ~(TopicPayload.Relationships | TopicPayload.References); // Return immediately if the resident topic already satisfies the requested scope - if (((ITopicLazyLoadable)topic).IsLoaded(gate, depth != 0)) { + if (((ITopicLazyLoadable)topic).IsLoaded(gate, depth)) { return; } diff --git a/OnTopic.Tests/ITopicLazyLoadableTest.cs b/OnTopic.Tests/ITopicLazyLoadableTest.cs index 1c027d56..e90a8ee6 100644 --- a/OnTopic.Tests/ITopicLazyLoadableTest.cs +++ b/OnTopic.Tests/ITopicLazyLoadableTest.cs @@ -14,7 +14,7 @@ namespace OnTopic.Tests; \-----------------------------------------------------------------------------------------------------------------------------*/ /// /// Provides unit tests for the interface, with a particular emphasis on the recursive overload. +/// cref="ITopicLazyLoadable.IsLoaded(TopicPayload, Int32)"/> overload. /// [ExcludeFromCodeCoverage] public class ITopicLazyLoadableTest { @@ -24,7 +24,7 @@ public class ITopicLazyLoadableTest { \---------------------------------------------------------------------------------------------------------------------------*/ /// /// Creates a topic with fully loaded extended attributes but a children collection. - /// Verifies that a non-recursive query returns true + /// Verifies that a non-recursive query returns true /// once the requested payload is satisfied, regardless of the state of . /// [Fact] @@ -36,7 +36,7 @@ public void IsLoaded_NonRecursive_IgnoresUnloadedChildren() { } }; - var result = topic.IsLoaded(TopicPayload.ExtendedAttributes, isRecursive: false); + var result = topic.IsLoaded(TopicPayload.ExtendedAttributes, depth: 0); Assert.True(result); @@ -47,7 +47,7 @@ public void IsLoaded_NonRecursive_IgnoresUnloadedChildren() { \---------------------------------------------------------------------------------------------------------------------------*/ /// /// Creates a topic with a single, unloaded child collection. Verifies that returns false for a recursive query, since the seed's returns false for a recursive query, since the seed's are not yet loaded. /// [Fact] @@ -59,7 +59,7 @@ public void IsLoaded_ShallowSeed_Recursive_ReturnsFalse() { } }; - Assert.False(topic.IsLoaded(TopicPayload.All, isRecursive: true)); + Assert.False(topic.IsLoaded(TopicPayload.All, depth: -1)); } @@ -68,7 +68,7 @@ public void IsLoaded_ShallowSeed_Recursive_ReturnsFalse() { \---------------------------------------------------------------------------------------------------------------------------*/ /// /// Creates a three-level topic hierarchy with every collection fully loaded. Verifies that returns true once the whole subtree is loaded. + /// cref="ITopicLazyLoadable.IsLoaded(TopicPayload, Int32)"/> returns true once the whole subtree is loaded. /// [Fact] public void IsLoaded_FullyResidentSubtree_Recursive_ReturnsTrue() { @@ -77,7 +77,7 @@ public void IsLoaded_FullyResidentSubtree_Recursive_ReturnsTrue() { var child = new Topic("Child", "Page", parent, 2); _ = new Topic("Grandchild", "Page", child, 3); - Assert.True(((ITopicLazyLoadable)parent).IsLoaded(TopicPayload.All, isRecursive: true)); + Assert.True(((ITopicLazyLoadable)parent).IsLoaded(TopicPayload.All, depth: -1)); } @@ -86,7 +86,7 @@ public void IsLoaded_FullyResidentSubtree_Recursive_ReturnsTrue() { \---------------------------------------------------------------------------------------------------------------------------*/ /// /// Creates a three-level topic hierarchy where the middle topic's extended attributes are . Verifies that returns + /// "LoadState.NotLoaded"/>. Verifies that returns /// false for a recursive query, even though the seed and its collection are fully /// loaded. /// @@ -99,7 +99,7 @@ public void IsLoaded_NotLoadedDescendant_Recursive_ReturnsFalse() { child.Attributes.LoadState = LoadState.NotLoaded; - Assert.False(((ITopicLazyLoadable)parent).IsLoaded(TopicPayload.ExtendedAttributes, isRecursive: true)); + Assert.False(((ITopicLazyLoadable)parent).IsLoaded(TopicPayload.ExtendedAttributes, depth: -1)); } @@ -109,7 +109,7 @@ public void IsLoaded_NotLoadedDescendant_Recursive_ReturnsFalse() { /// /// Creates a two-level topic hierarchy where the seed's collection is , and queries a payload parameter that excludes . - /// Verifies that still returns false, confirming + /// Verifies that still returns false, confirming /// that the children gate is evaluated independently of the requested payload before recursing. /// [Fact] @@ -120,7 +120,7 @@ public void IsLoaded_NotLoadedChildren_ExcludedPayload_Recursive_ReturnsFalse() parent.Children.LoadState = LoadState.NotLoaded; - var result = ((ITopicLazyLoadable)parent).IsLoaded(TopicPayload.ExtendedAttributes, isRecursive: true); + var result = ((ITopicLazyLoadable)parent).IsLoaded(TopicPayload.ExtendedAttributes, depth: -1); Assert.False(result); @@ -131,7 +131,7 @@ public void IsLoaded_NotLoadedChildren_ExcludedPayload_Recursive_ReturnsFalse() \---------------------------------------------------------------------------------------------------------------------------*/ /// /// Creates a topic stamped with a and a children - /// collection. Verifies that reads + /// collection. Verifies that reads /// directly and returns false without triggering a lazy load of . /// [Fact] @@ -144,7 +144,7 @@ public void IsLoaded_NotLoadedChildren_NeverTriggersLoad() { rawTopic.Loader = loader; topic.Children.LoadState = LoadState.NotLoaded; - var result = rawTopic.IsLoaded(TopicPayload.All, isRecursive: true); + var result = rawTopic.IsLoaded(TopicPayload.All, depth: -1); Assert.False(result); Assert.False(loader.WasCalled); diff --git a/OnTopic/Repositories/ITopicLazyLoadable.cs b/OnTopic/Repositories/ITopicLazyLoadable.cs index 208ba5f7..f021cfe9 100644 --- a/OnTopic/Repositories/ITopicLazyLoadable.cs +++ b/OnTopic/Repositories/ITopicLazyLoadable.cs @@ -65,11 +65,12 @@ bool IsLoaded(TopicPayload payload) { } /*============================================================================================================================ - | METHOD: IS LOADED (RECURSIVE) + | METHOD: IS LOADED (BY DEPTH) \---------------------------------------------------------------------------------------------------------------------------*/ /// /// Returns if every property flag in has already been fetched from the - /// underlying persistence store and, if , the same is true of every descendant. + /// underlying persistence store and, if is non-zero, the same is true of every descendant within + /// that depth. /// /// /// Recursion is gated on being fully before @@ -78,18 +79,19 @@ bool IsLoaded(TopicPayload payload) { /// should not trigger a lazy load. /// /// One or more flags to test. - /// - /// Determines whether descendants should also be evaluated against . + /// + /// The number of tiers of descendants that must also satisfy . -1 requires the full + /// subtree; 0 requires only this topic; N requires N tiers of descendants. /// - bool IsLoaded(TopicPayload payload, bool isRecursive) { + bool IsLoaded(TopicPayload payload, int depth) { // Evaluate current topic if (!IsLoaded(payload)) { return false; } - // Return if non-recursive - if (!isRecursive) { + // Return if seed-only + if (depth is 0) { return true; } @@ -100,7 +102,7 @@ bool IsLoaded(TopicPayload payload, bool isRecursive) { // Recurse over children foreach (var child in Children) { - if (!((ITopicLazyLoadable)child).IsLoaded(payload, isRecursive: true)) { + if (!((ITopicLazyLoadable)child).IsLoaded(payload, depth is -1 ? -1 : depth - 1)) { return false; } } From 5f1a815b0cb4525ef02650ec1eea8dd1aae1093b Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Mon, 27 Jul 2026 22:40:16 -0700 Subject: [PATCH 264/337] =?UTF-8?q?Update=20the=20test=20stub=20to=20suppo?= =?UTF-8?q?rt=20`Load(=E2=80=A6,=20depth)`?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This updates the `StubLazyLoadingTopicRepository ` to support `Load()` with `depth` instead of `isRecursive` (or the interim one-bit equivalent) (f09a43a1). This contributes to the testing of the depth-limited `Load()` task (#120). --- .../StubLazyLoadingTopicRepository.cs | 101 +++++++++++------- 1 file changed, 60 insertions(+), 41 deletions(-) diff --git a/OnTopic.TestDoubles/LazyLoading/StubLazyLoadingTopicRepository.cs b/OnTopic.TestDoubles/LazyLoading/StubLazyLoadingTopicRepository.cs index 8d4766db..8eb8f931 100644 --- a/OnTopic.TestDoubles/LazyLoading/StubLazyLoadingTopicRepository.cs +++ b/OnTopic.TestDoubles/LazyLoading/StubLazyLoadingTopicRepository.cs @@ -25,7 +25,7 @@ namespace OnTopic.TestDoubles.LazyLoading; /// /// /// Filling happens two ways, matching how a real, e.g., SQL-backed repository distinguishes a batch Load() from an -/// on-demand fill. and its overloads only connect association +/// on-demand fill. and its overloads only connect association /// targets already present in the graph being built, leaving the rest deferred; it never issues an additional fetch to /// resolve a missing target. , invoked either explicitly /// or via one of 's autoloading getters, goes further: It recursively loads whatever deferred targets it @@ -128,8 +128,8 @@ private static Topic BuildEagerScaffold() { public override async Task Load( string uniqueKey, Topic? referenceTopic = null, - bool isRecursive = false, - TopicPayload payload = TopicPayload.None + TopicPayload payload = TopicPayload.None, + int depth = 0 ) { // Validate unique key @@ -144,7 +144,7 @@ private static Topic BuildEagerScaffold() { // If the root is requested, hardcode the topicId at -1 if (uniqueKey.Equals(_root.Key, StringComparison.OrdinalIgnoreCase)) { - return await Load(-1, referenceTopic, isRecursive, payload).ConfigureAwait(false); + return await Load(-1, referenceTopic, payload, depth).ConfigureAwait(false); } // If the unique key isn't in the data store, return null @@ -153,7 +153,7 @@ private static Topic BuildEagerScaffold() { } // Otherwise, use the store's topicId to call the base overload - return await Load(topicId, referenceTopic, isRecursive, payload).ConfigureAwait(false); + return await Load(topicId, referenceTopic, payload, depth).ConfigureAwait(false); } @@ -163,14 +163,15 @@ private static Topic BuildEagerScaffold() { /// again: The event fires only when a topic is genuinely built for the first time, mirroring how a real repository only /// fires when something is actually pulled from the persistence store. On a miss against the record store, builds the /// requested topic and its ancestor chain as shallow, sparse topics, and raises the event for the requested topic. Either - /// way, if requests anything not yet loaded, it connects whatever it can from the graph already - /// built so far via ; targets that aren't yet resident stay deferred. + /// way, if or requests anything not yet loaded, it connects whatever it + /// can from the graph already built so far via ; targets that aren't yet resident stay + /// deferred. /// public override async Task Load( int topicId, Topic? referenceTopic = null, - bool isRecursive = false, - TopicPayload payload = TopicPayload.None + TopicPayload payload = TopicPayload.None, + int depth = 0 ) { // Setup @@ -197,13 +198,13 @@ await FillRequestedPayload( topic, payload, resolveDeferredTargets : false, - isRecursive, + depth, CancellationToken.None ).ConfigureAwait(false); // Fire the TopicLoaded event, if newly built if (isNewlyBuilt) { - OnTopicLoaded(new(topic, isRecursive)); + OnTopicLoaded(new(topic, depth)); } // Return the requested topic @@ -236,7 +237,7 @@ await FillRequestedPayload( topic.LastModified = version; // Fire the TopicLoaded event; this is always assumed to be freshly loaded - OnTopicLoaded(new(topic, false, version)); + OnTopicLoaded(new(topic, 0, version)); // Return the topic version return topic; @@ -281,7 +282,7 @@ protected override Task SaveTopic([NotNull]Topic topic, DateTime version, bool p \---------------------------------------------------------------------------------------------------------------------------*/ /// /// - /// The on-demand fill: Unlike , this recursively resolves deferred + /// The on-demand fill: Unlike , this recursively resolves deferred /// relationship and reference targets via the inherited LoadDeferredAssociations, discarding whatever remains /// unresolved as stale, assuming either or . /// @@ -300,7 +301,7 @@ await FillRequestedPayload( topic, payload, resolveDeferredTargets : true, - isRecursive : false, + depth : 0, cancellationToken ).ConfigureAwait(false); @@ -313,12 +314,12 @@ await FillRequestedPayload( /// On a plain Load(), connects resident relationship and reference targets unconditionally, regardless of /// . Either way, loads the data requested in , after filtering out /// any already flags, recording a fetch in the spy for each property filled. Children are - /// fetched from the record store one level at a time, unless is set, in which case - /// rides along so every descendant, not merely the immediate children, are - /// filled. A child already present in (e.g., attached while building an ancestor chain for a deeper - /// call, or eagerly preloaded) is reused rather than rebuilt, to - /// avoid colliding with the existing instance already attached to the graph, but is still offered the requested payload so - /// a resident child converges to the requested scope instead of being silently skipped. + /// fetched from the record store one tier at a time, decrementing at each level, until it reaches + /// 0; a of -1 descends the entire subtree. A child already present in (e.g., attached while building ancestor for a deeper + /// call, or eagerly preloaded) is reused rather than rebuilt, to avoid colliding with the existing instance already + /// attached to the graph, but is still offered the requested payload so a resident child converges to the requested scope + /// instead of being silently skipped. /// /// The topic whose requested payload should be filled. /// The requested flags. @@ -329,16 +330,18 @@ await FillRequestedPayload( /// Load(), which only connects targets already present in the graph, via the inherited . /// - /// - /// Whether a requested boundary should recurse into the entire subtree, - /// rather than filling only the immediate level. + /// + /// The number of tiers of descendants to fill below . -1 fills the full subtree; 0 + /// fills only itself, unless requests , in which case it is treated as 1, for continuity with 's + /// single-tier meaning. /// /// An optional token used only when resolving deferred targets. private async Task FillRequestedPayload( Topic topic, TopicPayload payload, bool resolveDeferredTargets, - bool isRecursive, + int depth, CancellationToken cancellationToken ) { @@ -369,14 +372,14 @@ CancellationToken cancellationToken \-------------------------------------------------------------------------------------------------------------------------*/ var requestedPayload = payload; - payload = ((ITopicLazyLoadable)topic).FilterPayload(payload); + // TopicPayload.Children continues to request one tier of children when no explicit depth is given + if (requestedPayload.HasFlag(TopicPayload.Children) && depth is 0) { + depth = 1; + } - // An isRecursive request for Children must still descend into an already-Loaded Children collection, since that only means - // this topic's immediate children are resident, not that their own descendants have converged to the requested scope; - // FilterPayload has no visibility into descendants, so it can't account for this on its own - var descendIntoChildren = isRecursive && requestedPayload.HasFlag(TopicPayload.Children); + payload = ((ITopicLazyLoadable)topic).FilterPayload(payload); - if (payload is TopicPayload.None && !descendIntoChildren) { + if (payload is TopicPayload.None && depth is 0) { return; } @@ -387,9 +390,15 @@ CancellationToken cancellationToken | Children >--------------------------------------------------------------------------------------------------------------------------- | Unlike ExtendedAttributes, Children never needs a record of its own to fill: It is resolved purely by scanning the store - | for records whose ParentId matches, including Root, whose top-level records are stored with a null ParentId + | for records whose ParentId matches, including Root, whose top-level records are stored with a null ParentId. Depth, not + | the Children flag, is the fetch axis: Any remaining depth descends, even if payload never requested Children directly, + | mirroring how a production @Depth-bounded fetch loads every tier within its bound regardless of which payload flags + | accompany it. \-------------------------------------------------------------------------------------------------------------------------*/ - if (payload.HasFlag(TopicPayload.Children) || descendIntoChildren) { + if (depth is not 0) { + + // Determine if the children are already loaded + var childrenAlreadyLoaded = ((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.Children); // Loop through each child record and build the topic from the topic store foreach (var childRecord in _store.Values.Where(r => (r.ParentId?? _root.Id) == topic.Id).OrderBy(r => r.Id)) { @@ -399,27 +408,37 @@ CancellationToken cancellationToken var isNewlyBuilt = !_served.TryGetValue(childRecord.Id, out var child); child ??= BuildTopic(childRecord, topic); + // Decrement the remaining depth budget for the child, unless unbounded (-1) + var childDepth = depth is -1 ? -1 : depth - 1; + // Load the rest of the requested payload for the child, mirroring how a Children fetch also pulls in whatever else was // requested (e.g., ExtendedAttributes, VersionHistory) for the whole scope, while relationships and references always - // ride along for free. When isRecursive, Children rides along too, so the fill descends into the entire subtree rather - // than stopping at one level. This uses requestedPayload, not the filtered payload, since a property that is already - // Loaded on a topic doesn't imply it's also already loaded on the child. This applies whether the child was just built - // or already served, so an existing child (e.g., eagerly preloaded) still converges to the requested scope - var childPayload = (isRecursive? requestedPayload : requestedPayload & ~TopicPayload.Children) + // ride along for free. Children rides along only while depth budget remains for the child, so the fill descends exactly + // as many tiers as requested, rather than stopping at one level or recursing unconditionally. This usesrequestedPayload + // not the filtered payload, since a property that is already Loaded on a topic doesn't imply it's also already loaded + // on the child. This applies whether the child was just built or already served, so an existing child (e.g., eagerly + // preloaded) still converges to the requested scope. + var childPayload = (childDepth is not 0 ? requestedPayload : requestedPayload & ~TopicPayload.Children) | TopicPayload.Relationships | TopicPayload.References; - await FillRequestedPayload(child, childPayload, resolveDeferredTargets: false, isRecursive, cancellationToken).ConfigureAwait(false); + await FillRequestedPayload( + child, + childPayload, + resolveDeferredTargets: false, + childDepth, + cancellationToken + ).ConfigureAwait(false); // Fire the TopicLoaded event, if newly built; an already served child was already announced when it was first built if (isNewlyBuilt) { - OnTopicLoaded(new(child, isRecursive)); + OnTopicLoaded(new(child, childDepth)); } } // Mark the children as fetched and loaded, if not already done; an already-Loaded Children collection, revisited only to - // descend for an isRecursive request, needs no re-fetch or re-stamp of its own - if (payload.HasFlag(TopicPayload.Children)) { + // descend for a deeper request, needs no re-fetch or re-stamp of its own + if (!childrenAlreadyLoaded) { RecordFetch(topic.Id, TopicPayload.Children); ((ITopicLazyLoadable)topic).SetLoadState(TopicPayload.Children, LoadState.Loaded); } From 33e36c41adbdaf3398b55e2b23e7f3f8e8ccedb0 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Mon, 27 Jul 2026 23:09:00 -0700 Subject: [PATCH 265/337] =?UTF-8?q?Update=20remaining=20stubs=20to=20suppo?= =?UTF-8?q?rt=20`Load(=E2=80=A6,=20depth)`?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The primary stub that will test the new Load(…, depth)` overload (f09a43a1) is `StubLazyLoadingTopicRepository` and so it was updated to support honoring the `depth` parameter (5f1a815b). The rest of the `ITopicRepository` stubs (and one dummy!) just need to honor the contract, without implementing the actual logic. This also includes docblock `cref`s referencing those `Load()` overloads, mostly within the test files themselves. This contributes to the testing of the depth-limited `Load()` task (#120). --- .../Repositories/StubTopicRepository.cs | 12 +++---- .../TestDoubles/TestTopicRepository.cs | 4 +-- OnTopic.TestDoubles/DummyTopicRepository.cs | 8 ++--- .../StubSitemapTopicRepository.cs | 6 ++-- OnTopic.TestDoubles/StubTopicRepository.cs | 14 ++++---- OnTopic.Tests/CachedTopicRepositoryTest.cs | 6 ++-- .../LazyLoadingTopicRepositoryTest.cs | 32 +++++++++---------- OnTopic.Tests/SqlTopicRepositoryTest.cs | 8 ++--- .../TestDoubles/FakeSqlTopicRepository.cs | 24 +++++++------- OnTopic.Tests/TopicRepositoryBaseTest.cs | 12 +++---- 10 files changed, 63 insertions(+), 63 deletions(-) diff --git a/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/Repositories/StubTopicRepository.cs b/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/Repositories/StubTopicRepository.cs index 73f45664..eb01b1a9 100644 --- a/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/Repositories/StubTopicRepository.cs +++ b/OnTopic.AspNetCore.Mvc.IntegrationTests.Host/Repositories/StubTopicRepository.cs @@ -45,8 +45,8 @@ public StubTopicRepository() { public override Task Load( int topicId, Topic? referenceTopic = null, - bool isRecursive = false, - TopicPayload payload = TopicPayload.None + TopicPayload payload = TopicPayload.None, + int depth = 0 ) { /*-------------------------------------------------------------------------------------------------------------------------- @@ -62,7 +62,7 @@ public StubTopicRepository() { | Raise event \-------------------------------------------------------------------------------------------------------------------------*/ if (topic != null) { - OnTopicLoaded(new(topic, isRecursive)); + OnTopicLoaded(new(topic, depth)); } /*-------------------------------------------------------------------------------------------------------------------------- @@ -76,8 +76,8 @@ public StubTopicRepository() { public override Task Load( string uniqueKey, Topic? referenceTopic = null, - bool isRecursive = false, - TopicPayload payload = TopicPayload.None + TopicPayload payload = TopicPayload.None, + int depth = 0 ) { /*-------------------------------------------------------------------------------------------------------------------------- @@ -96,7 +96,7 @@ public StubTopicRepository() { | Raise event \-------------------------------------------------------------------------------------------------------------------------*/ if (topic != null) { - OnTopicLoaded(new(topic, isRecursive)); + OnTopicLoaded(new(topic, depth)); } /*-------------------------------------------------------------------------------------------------------------------------- diff --git a/OnTopic.AspNetCore.Mvc.Tests/TestDoubles/TestTopicRepository.cs b/OnTopic.AspNetCore.Mvc.Tests/TestDoubles/TestTopicRepository.cs index e3a613e4..fda32721 100644 --- a/OnTopic.AspNetCore.Mvc.Tests/TestDoubles/TestTopicRepository.cs +++ b/OnTopic.AspNetCore.Mvc.Tests/TestDoubles/TestTopicRepository.cs @@ -49,8 +49,8 @@ public TestTopicRepository() { public override Task Load( string uniqueKey, Topic? referenceTopic = null, - bool isRecursive = false, - TopicPayload payload = TopicPayload.None + TopicPayload payload = TopicPayload.None, + int depth = 0 ) => Task.FromResult(String.IsNullOrEmpty(uniqueKey)? null : _cache.FindFirst(t => t.GetUniqueKey() == uniqueKey)); /*============================================================================================================================ diff --git a/OnTopic.TestDoubles/DummyTopicRepository.cs b/OnTopic.TestDoubles/DummyTopicRepository.cs index 38b80299..27cb1477 100644 --- a/OnTopic.TestDoubles/DummyTopicRepository.cs +++ b/OnTopic.TestDoubles/DummyTopicRepository.cs @@ -39,16 +39,16 @@ public DummyTopicRepository() { } public override Task Load( int topicId, Topic? referenceTopic = null, - bool isRecursive = false, - TopicPayload payload = TopicPayload.None + TopicPayload payload = TopicPayload.None, + int depth = 0 ) => Task.FromResult(null); /// public override Task Load( string uniqueKey, Topic? referenceTopic = null, - bool isRecursive = false, - TopicPayload payload = TopicPayload.None + TopicPayload payload = TopicPayload.None, + int depth = 0 ) => Task.FromResult(null); /// diff --git a/OnTopic.TestDoubles/StubSitemapTopicRepository.cs b/OnTopic.TestDoubles/StubSitemapTopicRepository.cs index 585f63ce..a2920286 100644 --- a/OnTopic.TestDoubles/StubSitemapTopicRepository.cs +++ b/OnTopic.TestDoubles/StubSitemapTopicRepository.cs @@ -17,8 +17,8 @@ namespace OnTopic.TestDoubles; /// /// /// Unlike a SQL-backed implementation, this does not source a lean, purpose-built graph; it simply defers to the wrapped -/// 's own , requesting -/// the full descendant tree explicitly since isRecursive defaults to false. +/// 's own , requesting +/// the full descendant tree explicitly since depth defaults to 0. /// /// The to source the sitemap's topic graph from. [ExcludeFromCodeCoverage] @@ -34,7 +34,7 @@ public class StubSitemapTopicRepository(ITopicRepository topicRepository) : ISit \---------------------------------------------------------------------------------------------------------------------------*/ /// public async Task Load() { - var topic = await _topicRepository.Load(-1, isRecursive: true).ConfigureAwait(false); + var topic = await _topicRepository.Load(-1, depth: -1).ConfigureAwait(false); Contract.Assume(topic, "The wrapped ITopicRepository did not return a topic graph."); return topic; } diff --git a/OnTopic.TestDoubles/StubTopicRepository.cs b/OnTopic.TestDoubles/StubTopicRepository.cs index 8f6650cb..9248f6dc 100644 --- a/OnTopic.TestDoubles/StubTopicRepository.cs +++ b/OnTopic.TestDoubles/StubTopicRepository.cs @@ -50,8 +50,8 @@ public StubTopicRepository() { public override Task Load( int topicId, Topic? referenceTopic = null, - bool isRecursive = false, - TopicPayload payload = TopicPayload.None + TopicPayload payload = TopicPayload.None, + int depth = 0 ) { /*-------------------------------------------------------------------------------------------------------------------------- @@ -67,7 +67,7 @@ public StubTopicRepository() { | Raise event \-------------------------------------------------------------------------------------------------------------------------*/ if (topic != null) { - OnTopicLoaded(new(topic, isRecursive)); + OnTopicLoaded(new(topic, depth)); } /*-------------------------------------------------------------------------------------------------------------------------- @@ -81,8 +81,8 @@ public StubTopicRepository() { public override Task Load( string uniqueKey, Topic? referenceTopic = null, - bool isRecursive = false, - TopicPayload payload = TopicPayload.None + TopicPayload payload = TopicPayload.None, + int depth = 0 ) { /*-------------------------------------------------------------------------------------------------------------------------- @@ -101,7 +101,7 @@ public StubTopicRepository() { | Raise event \-------------------------------------------------------------------------------------------------------------------------*/ if (topic != null) { - OnTopicLoaded(new(topic, isRecursive)); + OnTopicLoaded(new(topic, depth)); } /*-------------------------------------------------------------------------------------------------------------------------- @@ -136,7 +136,7 @@ public StubTopicRepository() { | Raise event \-------------------------------------------------------------------------------------------------------------------------*/ if (topic != null) { - OnTopicLoaded(new(topic, false, version)); + OnTopicLoaded(new(topic, 0, version)); } /*-------------------------------------------------------------------------------------------------------------------------- diff --git a/OnTopic.Tests/CachedTopicRepositoryTest.cs b/OnTopic.Tests/CachedTopicRepositoryTest.cs index 5c929091..65b14539 100644 --- a/OnTopic.Tests/CachedTopicRepositoryTest.cs +++ b/OnTopic.Tests/CachedTopicRepositoryTest.cs @@ -147,7 +147,7 @@ public async Task Load_ColdMissTwoLevelsBelowResidentAncestor_IndexesIntermediat /// /// Simulates the shape produced by , which attaches new topics to an /// existing parent without raising (and thus without indexing them), then calls - /// for the leaf and confirms the cache returns + /// for the leaf and confirms the cache returns /// the existing attached instances rather than duplicating them. The merge-aware underlying load reuses the loaded topics /// via the reference graph, and indexes both the leaf /// and any previously unindexed intermediate ancestor ("Web_0") by walking up the parent chain. @@ -314,7 +314,7 @@ public async Task Delete_LoadedTopic_SubsequentLoadDoesNotReturnDetachedInstance \---------------------------------------------------------------------------------------------------------------------------*/ /// /// Saves a newly created, unsaved under a resident parent, then calls for its newly assigned ID and confirms the same + /// "CachedTopicRepository.Load(int, Topic?, TopicPayload, int)"/> for its newly assigned ID and confirms the same /// instance is returned directly from the live index, with no fall-through to the inner repository. Ensures the setter's indexing hook from makes a freshly saved topic resolvable by ID. /// @@ -352,7 +352,7 @@ public async Task Save_NewTopic_ResolvesViaLoadWithoutFallback() { \---------------------------------------------------------------------------------------------------------------------------*/ /// /// Recursively saves a newly created parent with a newly created child underneath it, then calls for each of their newly assigned IDs and confirms both + /// "CachedTopicRepository.Load(int, Topic?, TopicPayload, int)"/> for each of their newly assigned IDs and confirms both /// resolve directly from the live index, with no fall-through to the inner repository. /// /// diff --git a/OnTopic.Tests/LazyLoadingTopicRepositoryTest.cs b/OnTopic.Tests/LazyLoadingTopicRepositoryTest.cs index 9969f7b8..6abee6bf 100644 --- a/OnTopic.Tests/LazyLoadingTopicRepositoryTest.cs +++ b/OnTopic.Tests/LazyLoadingTopicRepositoryTest.cs @@ -377,7 +377,7 @@ public async Task Children_MaterializedChild_IsItselfLazy() { \---------------------------------------------------------------------------------------------------------------------------*/ /// /// Loads a topic and confirms it carries a non-null , stamped through the public - /// /event path. + /// /event path. /// [Fact] public async Task Load_ServedNode_IsStamped() { @@ -721,8 +721,8 @@ public async Task Load_NarrowPayloadHit_TopsUpAndConverges() { var reloaded = await _cachedTopicRepository.Load( "Root:Web:Web_0:Web_0_0", topic, - false, - TopicPayload.ExtendedAttributes + TopicPayload.ExtendedAttributes, + 0 ); Assert.Same(topic, reloaded); @@ -747,12 +747,12 @@ public async Task Load_RecursiveHit_ConvergesSubtreeThenCleanHit() { var cache = new CachedTopicRepository(stub); var gate = TopicPayload.All & ~(TopicPayload.Relationships | TopicPayload.References); - var seed = await cache.Load("Root:Web:Web_0", null, true, TopicPayload.All); + var seed = await cache.Load("Root:Web:Web_0", null, TopicPayload.All, -1); - Assert.True(((ITopicLazyLoadable)seed!).IsLoaded(gate, isRecursive: true)); + Assert.True(((ITopicLazyLoadable)seed!).IsLoaded(gate, depth: -1)); var fetchesAfterFirstLoad = stub.TotalFetches; - var reloaded = await cache.Load("Root:Web:Web_0", null, true, TopicPayload.All); + var reloaded = await cache.Load("Root:Web:Web_0", null, TopicPayload.All, -1); Assert.Same(seed, reloaded); Assert.Equal(fetchesAfterFirstLoad, stub.TotalFetches); @@ -777,15 +777,15 @@ public async Task Load_RecursiveTopUpOnResidentSeed_AncestorsStayNotLoaded() { var deep = await _cachedTopicRepository.Load( "Root:Web:Web_0:Web_0_0", seed, - true, - TopicPayload.Children | TopicPayload.ExtendedAttributes + TopicPayload.Children | TopicPayload.ExtendedAttributes, + -1 ); - var ancestor = deep!.Parent; + var ancestor = deep!.Parent; Assert.Same(seed, deep); Assert.True( - ((ITopicLazyLoadable)deep).IsLoaded(TopicPayload.Children | TopicPayload.ExtendedAttributes, isRecursive: true) + ((ITopicLazyLoadable)deep).IsLoaded(TopicPayload.Children | TopicPayload.ExtendedAttributes, depth: -1) ); Assert.Equal("Extended body content for Web_0_0.", deep.Attributes.GetValue("Body")); Assert.False(((ITopicLazyLoadable)ancestor!).IsLoaded(TopicPayload.Children)); @@ -812,7 +812,7 @@ public async Task Load_RecursiveTopUp_InGraphCoreConnectsMergedRegion() { Assert.NotEmpty(rawTopic.Relationships.Deferred); Assert.NotEmpty(rawTopic.References.Deferred); - var web = await cache.Load("Root:Web", null, true, TopicPayload.Children); + var web = await cache.Load("Root:Web", null, TopicPayload.Children, -1); var web00 = web!.Children["Web_0"].Children["Web_0_0"]; var related = topic!.Relationships.GetValues("Related"); @@ -843,14 +843,14 @@ public async Task Load_WholeTreeTopUp_MaterializesThenCleanHit() { var cache = new CachedTopicRepository(stub); var gate = TopicPayload.All & ~(TopicPayload.Relationships | TopicPayload.References); - var seed = await cache.Load(-1, null, false, TopicPayload.None); + var seed = await cache.Load(-1, null, TopicPayload.None, 0); Assert.True(((ITopicLazyLoadable)seed!).IsLoaded(TopicPayload.Children)); - var loaded = await cache.Load(-1, seed, true, TopicPayload.All); + var loaded = await cache.Load(-1, seed, TopicPayload.All, -1); Assert.Same(seed, loaded); - Assert.True(((ITopicLazyLoadable)loaded!).IsLoaded(gate, isRecursive: true)); + Assert.True(((ITopicLazyLoadable)loaded!).IsLoaded(gate, depth: -1)); var web = loaded.Children["Web"]; @@ -863,8 +863,8 @@ public async Task Load_WholeTreeTopUp_MaterializesThenCleanHit() { web.Children["Web_0"].Children["Web_0_0"].Attributes.GetValue("Body") ); - var fetchesAfterLoad = stub.TotalFetches; - var reloaded = await cache.Load(-1, null, true, TopicPayload.All); + var fetchesAfterLoad = stub.TotalFetches; + var reloaded = await cache.Load(-1, null, TopicPayload.All, -1); Assert.Same(loaded, reloaded); Assert.Equal(fetchesAfterLoad, stub.TotalFetches); diff --git a/OnTopic.Tests/SqlTopicRepositoryTest.cs b/OnTopic.Tests/SqlTopicRepositoryTest.cs index f5c756a5..92e34068 100644 --- a/OnTopic.Tests/SqlTopicRepositoryTest.cs +++ b/OnTopic.Tests/SqlTopicRepositoryTest.cs @@ -503,10 +503,10 @@ public async Task LoadTopicGraph_PreExistingSingleChild_PreservesLoaded() { /// than downgraded by the ancestor crawl. /// /// - /// @LoadAscendants is passed for every - /// call outside of the root, regardless of isRecursive or payload, so the ancestor crawl runs on essentially every - /// load of anything beneath an already loaded ancestor. Without this guard, an already complete ancestor would be - /// perpetually reset to . + /// @LoadAscendants is passed for every + /// call outside of the root, regardless of depth or payload, so the ancestor crawl runs on essentially every load + /// of anything beneath an already loaded ancestor. Without this guard, an already complete ancestor would be perpetually + /// reset to . /// [Fact] public async Task LoadTopicGraph_PreExistingAncestor_PreservesLoaded() { diff --git a/OnTopic.Tests/TestDoubles/FakeSqlTopicRepository.cs b/OnTopic.Tests/TestDoubles/FakeSqlTopicRepository.cs index 8096d4ce..c9aa93ad 100644 --- a/OnTopic.Tests/TestDoubles/FakeSqlTopicRepository.cs +++ b/OnTopic.Tests/TestDoubles/FakeSqlTopicRepository.cs @@ -47,7 +47,7 @@ internal sealed class FakeSqlTopicRepository : TopicRepository { \---------------------------------------------------------------------------------------------------------------------------*/ /// /// Registers a row in the fake row store, keyed by , and indexes its unique key for lookups. + /// "Load(String, Topic?, TopicPayload, Int32)"/> lookups. /// public FakeSqlTopicRepository AddTopic(int id, string key, string contentType, int? parentId) { _rows[id] = (key, contentType, parentId); @@ -60,7 +60,7 @@ public FakeSqlTopicRepository AddTopic(int id, string key, string contentType, i \---------------------------------------------------------------------------------------------------------------------------*/ /// /// Registers a relationship row, returned alongside its source topic's ascendant chain on a subsequent . + /// "Load(Int32, Topic?, TopicPayload, Int32)"/>. /// public void AddRelationship(int sourceId, string key, int targetId) => _relationships.Add((sourceId, key, targetId)); @@ -97,13 +97,13 @@ private string GetUniqueKey(int id) { public override async Task Load( string uniqueKey, Topic? referenceTopic = null, - bool isRecursive = false, - TopicPayload payload = TopicPayload.None + TopicPayload payload = TopicPayload.None, + int depth = 0 ) { if (!_keyIndex.TryGetValue(uniqueKey, out var topicId)) { return null; } - return await Load(topicId, referenceTopic, isRecursive, payload).ConfigureAwait(false); + return await Load(topicId, referenceTopic, payload, depth).ConfigureAwait(false); } /// @@ -111,13 +111,13 @@ private string GetUniqueKey(int id) { /// Builds the requested topic's ascendant chain into fresh / rows on every call, then feeds them through the real —reproducing /// the new instance per call, reconciled against the referenceTopic behavior of . + /// "SqlTopicRepository.Load(Int32, Topic?, TopicPayload, Int32)"/>. /// public override async Task Load( int topicId, Topic? referenceTopic = null, - bool isRecursive = false, - TopicPayload payload = TopicPayload.None + TopicPayload payload = TopicPayload.None, + int depth = 0 ) { // Bypass for rowstore misses @@ -142,7 +142,7 @@ private string GetUniqueKey(int id) { ).ConfigureAwait(false); // Raise the TopicLoaded event - OnTopicLoaded(new(topic!, isRecursive)); + OnTopicLoaded(new(topic!, depth)); // Finally, return the seed topic return topic; @@ -160,7 +160,7 @@ void populateTopics(TopicsDataTable topics) { /// /// - /// Unlike , this builds a single-row , + /// Unlike , this builds a single-row , /// without the ascendant chain, and populated from rather than , then feeds it through with noreferenceTopic /// , mirroring production's detached GetTopicVersion: The returned has no - /// Shared core behind and : + /// Shared core behind and : /// Builds a fresh set of and rows, then feeds them /// through the real , exactly as does /// from a live reader. diff --git a/OnTopic.Tests/TopicRepositoryBaseTest.cs b/OnTopic.Tests/TopicRepositoryBaseTest.cs index e97be70c..cd086be5 100644 --- a/OnTopic.Tests/TopicRepositoryBaseTest.cs +++ b/OnTopic.Tests/TopicRepositoryBaseTest.cs @@ -54,7 +54,7 @@ public TopicRepositoryBaseTest() { | TEST: LOAD: VALID TOPIC ID: RETURNS EXPECTED TOPIC \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Calls with a valid + /// Calls with a valid /// and confirms that the expected topic is returned. /// [Fact] @@ -70,7 +70,7 @@ public async Task Load_ValidTopicId_ReturnsExpectedTopic() { | TEST: LOAD: INVALID TOPIC ID: RETURNS EXPECTED TOPIC \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Calls with an invalid with an invalid and confirms that no topic is returned. /// [Fact] @@ -81,7 +81,7 @@ public async Task Load_InvalidTopicId_ReturnsExpectedTopic() => | TEST: LOAD: NEGATIVE TOPIC ID: RETURNS ROOT TOPIC \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Calls with a negative with a negative and confirms that the root topic is returned. /// [Fact] @@ -92,7 +92,7 @@ public async Task Load_NegativeTopicId_ReturnsRootTopic() => | TEST: LOAD: NARROW PAYLOAD: RETURNS TOPIC \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Calls with payload set to with payload set to and confirms that a topic is still returned. The stub always returns fully-loaded topics /// regardless of this parameter; the test simply verifies the signature is accepted. /// @@ -109,7 +109,7 @@ public async Task Load_WithNarrowPayload_ReturnsTopic() { | TEST: LOAD: NARROW PAYLOAD: EXTENDED ATTRIBUTES LOADED \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Calls with payload set to with payload set to and confirms the extended-attribute boundary is . The stub does not /// defer extended attributes; this simply confirms no regression for stub-backed tests. /// @@ -1048,7 +1048,7 @@ public async Task Delete_AttributeDescriptor_UpdatesContentTypeCache() { | TEST: LOAD: TOPIC LOADED EVENT: IS RAISED \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Loads a topic using and ensures that the + /// Loads a topic using and ensures that the /// event is raised. /// [Fact] From 88160a480e184ba8eb8b39beed334f5146e20045 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 28 Jul 2026 00:10:25 -0700 Subject: [PATCH 266/337] Added unit tests for testing `depth` > 1 The previous unit tests were initially established based on `isRecursive` and `TopicPayload.Children` and thus effectively capture -1 (`isRecursive`), 0 (`!isRecursive`), and 1 (`TopicPayload.Children`). This complements those by adding tests that evaluate the _n_ case of `depth` greater than 1, which wasn't tested. This contributes to the testing of the depth-limited `Load()` task (#120). --- .../LazyLoadingTopicRepositoryTest.cs | 57 ++++++++++++++++++- 1 file changed, 56 insertions(+), 1 deletion(-) diff --git a/OnTopic.Tests/LazyLoadingTopicRepositoryTest.cs b/OnTopic.Tests/LazyLoadingTopicRepositoryTest.cs index 6abee6bf..24e4fbc2 100644 --- a/OnTopic.Tests/LazyLoadingTopicRepositoryTest.cs +++ b/OnTopic.Tests/LazyLoadingTopicRepositoryTest.cs @@ -873,7 +873,62 @@ public async Task Load_WholeTreeTopUp_MaterializesThenCleanHit() { #endregion - #region M: Deferred Dirty-State Propagation + #region M: Depth-Limited Loading + + /*============================================================================================================================ + | TEST: LOAD: DEPTH TWO: LOADS TWO TIERS + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Loads a topic with depth: 2 and confirms exactly two tiers of descendants are materialized: Both the seed's and + /// its child's are , while the grandchild's own children remain + /// , with no fetch recorded against it. Proves depth is modeled by decrementing per level, + /// not merely riding along as part of indefinite recursion (as would be expected with -1). + /// + [Fact] + public async Task Load_DepthTwo_LoadsTwoTiers() { + + var topic = await _loadingTopicRepository.Load("Root:Web", depth: 2); + var web0 = topic!.Children["Web_0"]; + var web00 = web0.Children["Web_0_0"]; + + Assert.True(((ITopicLazyLoadable)topic).IsLoaded(TopicPayload.Children)); + Assert.True(((ITopicLazyLoadable)web0).IsLoaded(TopicPayload.Children)); + Assert.False(((ITopicLazyLoadable)web00).IsLoaded(TopicPayload.Children)); + Assert.Equal(0, _loadingTopicRepository.GetFetchCount(web00.Id, TopicPayload.Children)); + + } + + /*============================================================================================================================ + | TEST: LOAD: DEPTH TWO: IS LOADED AGREES AT DEPTH ONE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Loads a topic with depth: 2 and confirms agrees + /// with exactly what was materialized. + /// + /// + /// Since is both the traversal axis and, here, the tested payload, the two are off by + /// one: A depth: 2 load promotes tiers 0 and 1 to but leaves tier 2 , since only its rows, and not its own children, were fetched. checks that every visited tier, including the deepest one, itself + /// satisfies the requested payload, so asking for Children at depth: 2 also demands the tier-2's own + /// Children be resolved, which a depth: 2 load never promotes. The query that agrees with a depth: 2 + /// load is therefore depth: 1, not depth: 2. + /// + [Fact] + public async Task Load_DepthTwo_IsLoadedAgreesAtDepthOne() { + + var topic = await _loadingTopicRepository.Load("Root:Web", depth: 2); + var rawTopic = (ITopicLazyLoadable)topic!; + + Assert.True(rawTopic.IsLoaded(TopicPayload.Children, depth: 1)); + Assert.False(rawTopic.IsLoaded(TopicPayload.Children, depth: 2)); + Assert.False(rawTopic.IsLoaded(TopicPayload.Children, depth: -1)); + + } + + #endregion + + #region N: Deferred Dirty-State Propagation /*============================================================================================================================ | TEST: ENSURE LOADED: DIRTY DEFERRED TARGET: RESOLVES AS DIRTY From d2c405eb047c2d755b9fb1398cdc13df658d34f5 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 28 Jul 2026 00:31:40 -0700 Subject: [PATCH 267/337] Add `@Depth` parameter to `GetTopics` sproc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This replaces the preexisting `@LoadChildren` (9c91f295) and `@LoadDescendants` (8c2c81da) parameters with the new `@Depth` parameter as part of the migration from `Load(…, isRecursive)` to `Load(…, depth)` (f09a43a1). This is the core database change for the depth-limited `Load()` task (#120). --- .../Stored Procedures/GetTopics.sql | 52 +++++++++++-------- OnTopic.Data.Sql/SqlTopicRepository.cs | 14 ++--- OnTopic.Tests/SqlTopicRepositoryTest.cs | 4 +- 3 files changed, 37 insertions(+), 33 deletions(-) diff --git a/OnTopic.Data.Sql.Database/Stored Procedures/GetTopics.sql b/OnTopic.Data.Sql.Database/Stored Procedures/GetTopics.sql index 01b41c42..fdfdd3de 100644 --- a/OnTopic.Data.Sql.Database/Stored Procedures/GetTopics.sql +++ b/OnTopic.Data.Sql.Database/Stored Procedures/GetTopics.sql @@ -7,9 +7,8 @@ CREATE PROCEDURE [dbo].[GetTopics] @TopicID INT = -1, - @LoadDescendants BIT = 1, + @Depth INT = 0, @LoadAscendants BIT = 0, - @LoadChildren BIT = 0, @IncludeIndexed BIT = 1, @IncludeExtended BIT = 1, @IncludeRelationships BIT = 1, @@ -47,9 +46,11 @@ CLUSTERED INDEX IX_C_Topics_TopicID ) -------------------------------------------------------------------------------------------------------------------------------- --- SELECT TOPIC AND DESCENDENTS +-- SELECT TOPIC AND DESCENDANTS (FULL SUBTREE) -------------------------------------------------------------------------------------------------------------------------------- -IF @LoadDescendants = 1 +-- A @Depth of -1 requests the entire subtree, efficiently expressed via a nested-set range join. +-------------------------------------------------------------------------------------------------------------------------------- +IF @Depth = -1 BEGIN INSERT #Topics ( TopicID, @@ -72,35 +73,44 @@ IF @LoadDescendants = 1 END -------------------------------------------------------------------------------------------------------------------------------- --- SELECT IMMEDIATE CHILDREN +-- SELECT TOPIC AND DESCENDANTS (BOUNDED) -------------------------------------------------------------------------------------------------------------------------------- --- Loads only the direct children of the requested topic. Mutually exclusive with LoadDescendants, as loading children of a --- subtree that is already being loaded is redundant. +-- A @Depth of 1 or more requests a bounded number of tiers below the seed topic, via a recursive CTE over ParentID. The seed is +-- included at level 0. SortOrder is populated from RangeLeft, guaranteeing parents precede children and preserve sibling order. -------------------------------------------------------------------------------------------------------------------------------- -ELSE IF @LoadChildren = 1 +ELSE IF @Depth >= 1 BEGIN + ;WITH DescendantsCTE AS ( + SELECT TopicID, + RangeLeft, + Level = 0 + FROM Topics + WHERE TopicID = @TopicID + UNION ALL + SELECT T1.TopicID, + T1.RangeLeft, + Level = DescendantsCTE.Level + 1 + FROM Topics AS T1 + INNER JOIN DescendantsCTE + ON T1.ParentID = DescendantsCTE.TopicID + WHERE DescendantsCTE.Level < @Depth + ) INSERT #Topics ( TopicID, SortOrder ) - SELECT T1.TopicID, - T1.RangeLeft - FROM Topics AS T1 - WHERE T1.ParentID = @TopicID - ORDER BY T1.RangeLeft - OPTION ( - OPTIMIZE - FOR ( @TopicID UNKNOWN - ) - ) + SELECT TopicID, + RangeLeft + FROM DescendantsCTE + OPTION (MAXRECURSION 0) END -------------------------------------------------------------------------------------------------------------------------------- -- SELECT TOPIC AND ANCESTOR CHAIN -------------------------------------------------------------------------------------------------------------------------------- -- Ancestors are rows whose nested-set range contains the requested node's RangeLeft, i.e., the mirror of the descendant query --- above. This can be combined with LoadDescendants to load both the subtree and its ancestor chain in a single query. The NOT --- EXISTS guard prevents duplicate inserts when both are requested. +-- above. This can be combined with @Depth to load both the subtree and its ancestor chain in a single query. The NOT EXISTS +-- guard prevents duplicate inserts when both are requested. -------------------------------------------------------------------------------------------------------------------------------- IF @LoadAscendants = 1 BEGIN @@ -135,7 +145,7 @@ IF @LoadAscendants = 1 -- Inserts only the requested topic; used by the lazy-load resolver to fill a single topic's extended attributes without -- traversing the tree in either direction. -------------------------------------------------------------------------------------------------------------------------------- -IF @LoadDescendants = 0 AND @LoadChildren = 0 AND @LoadAscendants = 0 +IF @Depth = 0 AND @LoadAscendants = 0 BEGIN INSERT #Topics ( TopicID, diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs index 4dd7b969..dd4c61f4 100644 --- a/OnTopic.Data.Sql/SqlTopicRepository.cs +++ b/OnTopic.Data.Sql/SqlTopicRepository.cs @@ -145,14 +145,9 @@ public SqlTopicRepository(string connectionString) { /*-------------------------------------------------------------------------------------------------------------------------- | Establish query parameters - >------------------------------------------------------------------------------------------------------------------------- - | Interim mapping of depth onto GetTopics' boolean parameters until a depth-aware @Depth parameter: -1 loads the full - | subtree; 1 loads one tier of children; 0 loads neither; N ≥ 2 is a documented superset that over-fetches the full subtree - | until @Depth is wired up. \-------------------------------------------------------------------------------------------------------------------------*/ command.AddParameter("TopicID", topicId); - command.AddParameter("LoadDescendants", depth is (-1) or >= 2); - command.AddParameter("LoadChildren", depth is 1); + command.AddParameter("Depth", depth); command.AddParameter("LoadAscendants", topicId >= 0); command.AddParameter("IncludeExtended", payload.HasFlag(TopicPayload.ExtendedAttributes)); command.AddParameter("IncludeRelationships", true); @@ -787,7 +782,7 @@ protected override sealed async Task DeleteTopic(Topic topic) { /// setting the payload parameters based on the requested . /// /// - /// Indexed attributes and associations are only requested when filling the boundary, + /// Indexed attributes and associations are only requested when filling the property, /// as they are otherwise always loaded as part of the initial for /// existing topics. /// @@ -796,10 +791,9 @@ private static void AddEnsureLoadedParameters(SqlCommand command, int topicId, T // Set the topic we're working with command.AddParameter("TopicID", topicId); - // Scope: LoadChildren when filling the Children, otherwise we're only interested in this topic's content - command.AddParameter("LoadDescendants", false); + // Scope: One tier of children when filling the Children property, otherwise just this topic's own content + command.AddParameter("Depth", payload.HasFlag(TopicPayload.Children) ? 1 : 0); command.AddParameter("LoadAscendants", false); - command.AddParameter("LoadChildren", payload.HasFlag(TopicPayload.Children)); // Payload: Include only what the requested payload requires; relationships and references are loaded during the initial // Load() call, so they do not need to be re-fetched diff --git a/OnTopic.Tests/SqlTopicRepositoryTest.cs b/OnTopic.Tests/SqlTopicRepositoryTest.cs index 92e34068..3efc8cc2 100644 --- a/OnTopic.Tests/SqlTopicRepositoryTest.cs +++ b/OnTopic.Tests/SqlTopicRepositoryTest.cs @@ -1017,8 +1017,8 @@ public async Task LoadTopicGraph_WithHasChildrenOnAncestorAndLoadedSubtree_SetsL | TEST: LOAD TOPIC GRAPH: WITH ONE LEVEL OF CHILDREN: CONVERGES SEED, LEAVES GRANDCHILDREN NOT LOADED \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Calls with a result set shaped like a non-recursive - /// @LoadChildren call, with the seed's immediate child present, but that child's own children are not, and confirms the + /// Calls with a result set shaped like a @Depth: 1 call, with + /// the seed's immediate child present, but that child's own children are not, and confirms the /// seed converges to while the child (which received no rows of its own) remains . /// From ce39fa15878a1e274d97a0b17e0f9bf70a70b4d7 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 28 Jul 2026 00:34:21 -0700 Subject: [PATCH 268/337] Added a new index for `ParentID` This optimizes for the `@Depth` argument in the `GetTopics` stored procedure (d2c405eb), to better support the depth-limited `Load()` task (#120). --- OnTopic.Data.Sql.Database/Tables/Topics.sql | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/OnTopic.Data.Sql.Database/Tables/Topics.sql b/OnTopic.Data.Sql.Database/Tables/Topics.sql index c4bda366..ace9e6da 100644 --- a/OnTopic.Data.Sql.Database/Tables/Topics.sql +++ b/OnTopic.Data.Sql.Database/Tables/Topics.sql @@ -53,4 +53,18 @@ CREATE NONCLUSTERED INDEX [IX_Topics_RangeRight] ON [dbo].[Topics] ( [RangeRight] ASC + ); + +GO + +-------------------------------------------------------------------------------------------------------------------------------- +-- PARENT ID (INDEX) +-------------------------------------------------------------------------------------------------------------------------------- +-- Provides a dedicated index for evaluating a topic's immediate children, e.g. via the depth-bound recursive CTE in GetTopics. +-- The (TopicKey, ParentID) unique constraint already indexes ParentID, but in the wrong order for this predicate. +-------------------------------------------------------------------------------------------------------------------------------- +CREATE NONCLUSTERED +INDEX [IX_Topics_ParentID] + ON [dbo].[Topics] ( + [ParentID] ASC ); \ No newline at end of file From 24aba97b17057a869ada2cf9e24626250fdae907 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 28 Jul 2026 00:45:42 -0700 Subject: [PATCH 269/337] Added unit tests for testing `depth` > 1 (cont.) This extends the previously established testing (88160a48) of the depth-limited `Load()` task (#120) to include two additional unit tests focusing on convergence of overlapping requests. --- .../LazyLoadingTopicRepositoryTest.cs | 52 +++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/OnTopic.Tests/LazyLoadingTopicRepositoryTest.cs b/OnTopic.Tests/LazyLoadingTopicRepositoryTest.cs index 24e4fbc2..071a951b 100644 --- a/OnTopic.Tests/LazyLoadingTopicRepositoryTest.cs +++ b/OnTopic.Tests/LazyLoadingTopicRepositoryTest.cs @@ -871,6 +871,58 @@ public async Task Load_WholeTreeTopUp_MaterializesThenCleanHit() { } + /*============================================================================================================================ + | TEST: LOAD: DEPTH TWO THEN UNBOUNDED: TOPS UP REMAINING TIERS + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Loads a subtree to depth: 2, confirms the gate agrees only through depth: 1 (i.e., the deepest fetched + /// tier's own children are not yet resolved), then tops the same seed up to depth: -1 and confirms the whole subtree + /// converges against the same instance, proving a partial-depth region reissues one deep load and merges without a + /// perpetual-reload loop. + /// + [Fact] + public async Task Load_DepthTwoThenUnbounded_TopsUpRemainingTiers() { + + var stub = new StubLazyLoadingTopicRepository(); + var cache = new CachedTopicRepository(stub); + var gate = TopicPayload.All & ~(TopicPayload.Relationships | TopicPayload.References); + + var seed = await cache.Load("Root:Web", null, TopicPayload.All, 2); + + Assert.True(((ITopicLazyLoadable)seed!).IsLoaded(gate, depth: 1)); + Assert.False(((ITopicLazyLoadable)seed).IsLoaded(gate, depth: 2)); + + var deep = await cache.Load("Root:Web", seed, TopicPayload.All, -1); + + Assert.Same(seed, deep); + Assert.True(((ITopicLazyLoadable)deep!).IsLoaded(gate, depth: -1)); + + } + + /*============================================================================================================================ + | TEST: LOAD: DEPTH TWO THEN DEPTH ONE: IS CLEAN HIT + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Loads a subtree to depth: 2, then re-requests it at the shallower depth: 1, and confirms the second call + /// is a converged hit: The same instance is returned and no further fetches are recorded, proving the gate treats a deeper + /// resident region as sufficient for a shallower request rather than re-fetching. + /// + [Fact] + public async Task Load_DepthTwoThenDepthOne_IsCleanHit() { + + var stub = new StubLazyLoadingTopicRepository(); + var cache = new CachedTopicRepository(stub); + + var seed = await cache.Load("Root:Web", null, TopicPayload.All, 2); + var fetchesAfterFirstLoad = stub.TotalFetches; + + var reloaded = await cache.Load("Root:Web", seed, TopicPayload.All, 1); + + Assert.Same(seed, reloaded); + Assert.Equal(fetchesAfterFirstLoad, stub.TotalFetches); + + } + #endregion #region M: Depth-Limited Loading From ca8bb8f25af4c222f5b4eaa21d25beaa49539b25 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 28 Jul 2026 02:50:28 -0700 Subject: [PATCH 270/337] =?UTF-8?q?Pre-normalize=20key=20in=20calls=20to?= =?UTF-8?q?=20`Load(uniqueKey,=20=E2=80=A6)`?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit At least with `CachedTopicRepository`'s `Load(uniqueKey, …)` overload, the `uniqueKey` is already normalized. In that case, this isn't strictly necessary, but is also a cheap way to avoid unnecessary normalization on a predictable path. With `SqlTopicRepository`, however, the `Load(uniqueKey, …)` overload doesn't actually do any normalization, so in the case that we're not using an `TopicRepositoryDecorator`, as with `CachedTopicRepository`, these calls would have failed, an longstanding preexisting bug. In a future update, I'll be patching that bug by centralizing the `uniqueKey` normalization and making sure it's shared across `ITopicRepository` implementations. Until then, regardless, this is both a minor-but-easy optimization, plus a way to avoid that inconsistency. --- OnTopic.AspNetCore.Mvc/Components/MenuViewComponentBase{T}.cs | 2 +- .../Hierarchical/CachedHierarchicalTopicMappingService{T}.cs | 2 +- .../Mapping/Hierarchical/IHierarchicalTopicMappingService{T}.cs | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/OnTopic.AspNetCore.Mvc/Components/MenuViewComponentBase{T}.cs b/OnTopic.AspNetCore.Mvc/Components/MenuViewComponentBase{T}.cs index cc952877..6a7a4978 100644 --- a/OnTopic.AspNetCore.Mvc/Components/MenuViewComponentBase{T}.cs +++ b/OnTopic.AspNetCore.Mvc/Components/MenuViewComponentBase{T}.cs @@ -84,7 +84,7 @@ IHierarchicalTopicMappingService hierarchicalTopicMappingService if (!String.IsNullOrEmpty(configuredRoot)) { navigationRootTopic = TopicRepository.Load("Root:" + configuredRoot, CurrentTopic).GetAwaiter().GetResult(); } - navigationRootTopic ??= HierarchicalTopicMappingService.GetHierarchicalRoot(CurrentTopic, 2, "Web"); + navigationRootTopic ??= HierarchicalTopicMappingService.GetHierarchicalRoot(CurrentTopic, 2, "Root:Web"); /*-------------------------------------------------------------------------------------------------------------------------- | Return root diff --git a/OnTopic/Mapping/Hierarchical/CachedHierarchicalTopicMappingService{T}.cs b/OnTopic/Mapping/Hierarchical/CachedHierarchicalTopicMappingService{T}.cs index 05c4049f..13be551b 100644 --- a/OnTopic/Mapping/Hierarchical/CachedHierarchicalTopicMappingService{T}.cs +++ b/OnTopic/Mapping/Hierarchical/CachedHierarchicalTopicMappingService{T}.cs @@ -53,7 +53,7 @@ IHierarchicalTopicMappingService hierarchicalTopicMappingService | GET HIERARCHICAL ROOT \---------------------------------------------------------------------------------------------------------------------------*/ /// - public Topic? GetHierarchicalRoot(Topic? currentTopic, int fromRoot = 2, string defaultRoot = "Web") => + public Topic? GetHierarchicalRoot(Topic? currentTopic, int fromRoot = 2, string defaultRoot = "Root:Web") => _hierarchicalTopicMappingService.GetHierarchicalRoot(currentTopic, fromRoot, defaultRoot); /*============================================================================================================================ diff --git a/OnTopic/Mapping/Hierarchical/IHierarchicalTopicMappingService{T}.cs b/OnTopic/Mapping/Hierarchical/IHierarchicalTopicMappingService{T}.cs index 4bffb1f3..4a5eb565 100644 --- a/OnTopic/Mapping/Hierarchical/IHierarchicalTopicMappingService{T}.cs +++ b/OnTopic/Mapping/Hierarchical/IHierarchicalTopicMappingService{T}.cs @@ -48,7 +48,7 @@ namespace OnTopic.Mapping.Hierarchical; /// The to start from. /// The distance that the navigation root should be from the root of the topic graph. /// If a root cannot be identified, the default root that should be returned. - Topic? GetHierarchicalRoot(Topic? currentTopic, int fromRoot = 2, string defaultRoot = "Web"); + Topic? GetHierarchicalRoot(Topic? currentTopic, int fromRoot = 2, string defaultRoot = "Root:Web"); /*============================================================================================================================ | GET ROOT VIEW MODEL (ASYNC) From 1879ce8a7a52d9fd6019a358cf64a7b0a5f9dd8c Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 28 Jul 2026 15:20:07 -0700 Subject: [PATCH 271/337] Removed task queue for hierarchical mapping When I first implemented the `HierarchicalTopicMappingService`, I introduced a task queue to improve performance. But this is a CPU-bound operation, not an I/O-bound operation, and I wasn't parallelizing it on multiple threads, so it really was a pretty naive implementation. Further, it introduced potential race conditions which could corrupt the ordering of items in the navigation. So not only was it likely not faster, but it was potentially slower and incorrect. And since, in practice, this layer will be cached via the `CachedHierarchicalTopicMappingService`, it's really not offering significant gain. Given that, I'm treating this as a preexisting bug, and removing it outright. --- .../HierarchicalTopicMappingService{T}.cs | 18 ++++-------------- 1 file changed, 4 insertions(+), 14 deletions(-) diff --git a/OnTopic/Mapping/Hierarchical/HierarchicalTopicMappingService{T}.cs b/OnTopic/Mapping/Hierarchical/HierarchicalTopicMappingService{T}.cs index 3b2a4642..22642fa9 100644 --- a/OnTopic/Mapping/Hierarchical/HierarchicalTopicMappingService{T}.cs +++ b/OnTopic/Mapping/Hierarchical/HierarchicalTopicMappingService{T}.cs @@ -145,7 +145,6 @@ private static int DistanceFromRoot(Topic sourceTopic) { /*-------------------------------------------------------------------------------------------------------------------------- | Establish variables \-------------------------------------------------------------------------------------------------------------------------*/ - List> taskQueue = []; List children = []; var viewModel = (T?)null; @@ -169,19 +168,10 @@ private static int DistanceFromRoot(Topic sourceTopic) { \-------------------------------------------------------------------------------------------------------------------------*/ if (tiers >= 0 && viewModel.Children.Count == 0) { foreach (var topic in sourceTopic.Children.Where(t => t.IsVisible() && validationDelegate(t))) { - taskQueue.Add(GetViewModelAsync(topic, tiers, validationDelegate)); - } - } - - /*-------------------------------------------------------------------------------------------------------------------------- - | Process children - \-------------------------------------------------------------------------------------------------------------------------*/ - while (taskQueue.Count > 0 && viewModel.Children.Count == 0) { - var dtoTask = await Task.WhenAny(taskQueue).ConfigureAwait(false); - var dto = await dtoTask.ConfigureAwait(false); - taskQueue.Remove(dtoTask); - if (dto is not null) { - children.Add(dto); + var dto = await GetViewModelAsync(topic, tiers, validationDelegate).ConfigureAwait(false); + if (dto is not null) { + children.Add(dto); + } } } From c223699cc827c049399fcb33c946a8c63415d576 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 28 Jul 2026 15:26:46 -0700 Subject: [PATCH 272/337] Preload the hierarchy before mapping MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit If we map the hierarchy progressively, as we did before, it would trigger a `Load()` for each unloaded child, which will be common when initializing a site. Instead, this takes advantage of the new `Load(…, depth)` argument (f09a43a1, d2c405eb) to load the exact depth of the hierarchy upfront, so there shouldn't be the need for any further fetches (unless extended attributes are requested). This is one of the primary use cases for introducing the depth-limited `Load()` (#120), and a real benefit when warming the initial cache, as it'd otherwise be a regression in terms of the benefits of the lazy-loading project (#111). --- .../HierarchicalTopicMappingService{T}.cs | 38 ++++++++++++++++++- 1 file changed, 37 insertions(+), 1 deletion(-) diff --git a/OnTopic/Mapping/Hierarchical/HierarchicalTopicMappingService{T}.cs b/OnTopic/Mapping/Hierarchical/HierarchicalTopicMappingService{T}.cs index 22642fa9..c1dca371 100644 --- a/OnTopic/Mapping/Hierarchical/HierarchicalTopicMappingService{T}.cs +++ b/OnTopic/Mapping/Hierarchical/HierarchicalTopicMappingService{T}.cs @@ -128,12 +128,48 @@ private static int DistanceFromRoot(Topic sourceTopic) { | GET VIEW MODEL (ASYNC) \---------------------------------------------------------------------------------------------------------------------------*/ /// + /// + /// Warms the requested -deep region in a single round-trip before recursing into , so there's no need to lazy load children during the recursive descent. Skipped + /// for an unsaved () since the topic's Id of -1 is + /// treated by as a request for the root of the + /// entire graph, not a itself, so this would fetch the wrong node's descendants. + /// public async Task GetViewModelAsync( Topic? sourceTopic, int tiers = 1, Func? validationDelegate = null ) { + /*-------------------------------------------------------------------------------------------------------------------------- + | Load the requested region + \-------------------------------------------------------------------------------------------------------------------------*/ + if (sourceTopic is not null && !sourceTopic.IsNew && tiers > 0) { + await TopicRepository.Load(sourceTopic.Id, sourceTopic, depth: tiers).ConfigureAwait(false); + } + + /*-------------------------------------------------------------------------------------------------------------------------- + | Delegate mapping once reference topic is resolved + \-------------------------------------------------------------------------------------------------------------------------*/ + return await GetHierarchicalTopicViewModelAsync(sourceTopic, tiers, validationDelegate).ConfigureAwait(false); + + } + + /*============================================================================================================================ + | GET HIERARCHICAL VIEW MODEL (ASYNC) + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Recursively maps each and its descendants, up to deep. + /// + /// The to map. + /// The number of tiers of descendants, relative to , to include. + /// An optional function to validate whether a topic should be included. + private async Task GetHierarchicalTopicViewModelAsync( + Topic? sourceTopic, + int tiers, + Func? validationDelegate + ) { + /*-------------------------------------------------------------------------------------------------------------------------- | Validate preconditions \-------------------------------------------------------------------------------------------------------------------------*/ @@ -168,7 +204,7 @@ private static int DistanceFromRoot(Topic sourceTopic) { \-------------------------------------------------------------------------------------------------------------------------*/ if (tiers >= 0 && viewModel.Children.Count == 0) { foreach (var topic in sourceTopic.Children.Where(t => t.IsVisible() && validationDelegate(t))) { - var dto = await GetViewModelAsync(topic, tiers, validationDelegate).ConfigureAwait(false); + var dto = await GetHierarchicalTopicViewModelAsync(topic, tiers, validationDelegate).ConfigureAwait(false); if (dto is not null) { children.Add(dto); } From 8fe46dc838e2958066eb1f3289f8827fec1cf0e1 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 28 Jul 2026 16:45:28 -0700 Subject: [PATCH 273/337] Added unit tests for tiered hierarchical load This introduces two tests to evaluate the new integration of the depth-limited loading (#120) into the `HierarchicalTopicRepository` (c223699c). The first confirms that two tiers requested are delivered without a second lazy-load. The second confirms that a non-saved topic is not mapped. --- .../HierarchicalTopicMappingServiceTest.cs | 71 ++++++++++++++++++- 1 file changed, 69 insertions(+), 2 deletions(-) diff --git a/OnTopic.Tests/HierarchicalTopicMappingServiceTest.cs b/OnTopic.Tests/HierarchicalTopicMappingServiceTest.cs index 14b67f26..40a3db7c 100644 --- a/OnTopic.Tests/HierarchicalTopicMappingServiceTest.cs +++ b/OnTopic.Tests/HierarchicalTopicMappingServiceTest.cs @@ -4,10 +4,15 @@ | Project Topics Library \=============================================================================================================================*/ using OnTopic.Data.Caching; +using OnTopic.Lookup; +using OnTopic.Mapping; using OnTopic.Mapping.Hierarchical; using OnTopic.Repositories; using OnTopic.TestDoubles; +using OnTopic.TestDoubles.LazyLoading; using OnTopic.Tests.Fixtures; +using OnTopic.Tests.TestDoubles; +using OnTopic.ViewModels; using Xunit; namespace OnTopic.Tests; @@ -136,17 +141,20 @@ public void GetHierarchicalRoot_WithDeepTopic_ReturnsRoot() { \---------------------------------------------------------------------------------------------------------------------------*/ /// /// Calls method - /// and ensures that the expected data is returned. + /// and ensures that the expected data is returned, with children landing in the same order as + /// (i.e., source order), confirming the sequential foreach fan-out never reorders on completion. /// [Fact] public async Task GetViewModel_WithTwoLevels_ReturnsGraph() { var rootTopic = await _topicRepository.Load("Root:Web"); - var viewModel = await _hierarchicalMappingService.GetViewModelAsync(rootTopic, 1); + var expectedOrder = rootTopic!.Children.Select(t => t.GetWebPath()).ToList(); + var viewModel = await _hierarchicalMappingService.GetViewModelAsync(rootTopic, 1); Assert.NotNull(viewModel); Assert.Equal(3, viewModel.Children.Count); Assert.Empty(viewModel.Children[0].Children); + Assert.Equal(expectedOrder, viewModel.Children.Select(c => c.WebPath)); } @@ -199,4 +207,63 @@ public async Task GetViewModel_WithDisabled_ExcludesDisabled() { } + /*============================================================================================================================ + | TEST: GET VIEW MODEL: DEPTH TWO: WARMS ONCE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Calls with tiers: 2 against a fresh , and confirms the region is warmed in a single round-trip: An identical second call + /// is a clean, converged hit that issues no further fetches, proving the recursive descent never falls back to per-node + /// lazy loads. + /// + [Fact] + public async Task GetViewModel_DepthTwo_WarmsOnce() { + + var stub = new StubLazyLoadingTopicRepository(); + var cache = new CachedTopicRepository(stub); + var typeLookupService = new CompositeTypeLookupService(new TopicViewModelLookupService(), new FakeViewModelLookupService()); + var mappingService = new TopicMappingService(cache, typeLookupService); + var hierarchicalService = new HierarchicalTopicMappingService(cache, mappingService); + + var webTopic = await cache.Load("Root:Web"); + + var viewModel = await hierarchicalService.GetViewModelAsync(webTopic, 2); + var fetchesAfterFirstMap = stub.TotalFetches; + + Assert.NotNull(viewModel); + + _ = await hierarchicalService.GetViewModelAsync(webTopic, 2); + + Assert.Equal(fetchesAfterFirstMap, stub.TotalFetches); + + } + + /*============================================================================================================================ + | TEST: GET VIEW MODEL: NEW SOURCE TOPIC: ISSUES NO LOAD + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Calls against an unsaved () and confirms the warm-up load is skipped: An unsaved topic's Id of -1 would + /// otherwise route , loading the root node, rather + /// than warming the intended region. + /// + [Fact] + public async Task GetViewModel_NewSourceTopic_IssuesNoLoad() { + + var stub = new StubLazyLoadingTopicRepository(); + var cache = new CachedTopicRepository(stub); + var typeLookupService = new CompositeTypeLookupService(new TopicViewModelLookupService(), new FakeViewModelLookupService()); + var mappingService = new TopicMappingService(cache, typeLookupService); + var hierarchicalService = new HierarchicalTopicMappingService(cache, mappingService); + + var newTopic = new Topic("Test", "Page"); + var fetchesBeforeMap = stub.TotalFetches; + + var viewModel = await hierarchicalService.GetViewModelAsync(newTopic, 2); + + Assert.NotNull(viewModel); + Assert.Equal(fetchesBeforeMap, stub.TotalFetches); + + } + } //Class \ No newline at end of file From 36f6b5f09ac8a3d6a83b3702b26ec57edad84d25 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 28 Jul 2026 16:47:46 -0700 Subject: [PATCH 274/337] Add unit tests for loading boolean values This provides two unit tests for the `AttributeCollection` and the new `autoLoad` parameter (aecee854) which is already presumed with `GetBoolean()` (42495b9d). The first confirms that calling `Topic.IsVisible`, which is backed by `Attributes.GetBoolean()`, doesn't trigger an autoload of the extended attributes. The second does the same thing with `IsHidden`, but derives the value from a `BaseTopic`, which it already presumes to be in memory. A subsequent test will evaluate the lazy loading of that scenario. --- OnTopic.Tests/AttributeCollectionTest.cs | 52 ++++++++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/OnTopic.Tests/AttributeCollectionTest.cs b/OnTopic.Tests/AttributeCollectionTest.cs index 1a9ddaa4..082c6e1d 100644 --- a/OnTopic.Tests/AttributeCollectionTest.cs +++ b/OnTopic.Tests/AttributeCollectionTest.cs @@ -9,6 +9,7 @@ using OnTopic.Repositories; using OnTopic.Tests.Entities; using OnTopic.Tests.TestDoubles; +using OnTopic.TestDoubles.LazyLoading; using Xunit; namespace OnTopic.Tests; @@ -487,6 +488,57 @@ public void GetBoolean_NotLoaded_KeyAbsent_SuppressesAutoLoad() { } + /*============================================================================================================================ + | TEST: IS VISIBLE: NOT LOADED EXTENDED ATTRIBUTES TOPIC: PERFORMS ZERO FILLS + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Calls on a topic with pending, not-yet-loaded extended attributes, and confirms + /// it performs zero fills: and are indexed attributes and must + /// never trigger the extended attributes to be fetched merely to determine visibility. + /// + [Fact] + public async Task IsVisible_NotLoadedExtendedAttributesTopic_PerformsZeroFills() { + + var records = new StubLazyLoadingTopicRepositoryBuilder() + .AddTopic(201, "Sparse", "Page", null, extendedAttributes: new Dictionary { ["Summary"] = "Some text." }) + .Build(); + + var stub = new StubLazyLoadingTopicRepository(records); + var topic = await stub.Load("Root:Sparse"); + + Assert.True(topic!.IsVisible()); + Assert.Equal(0, stub.GetFetchCount(201, TopicPayload.ExtendedAttributes)); + + } + + /*============================================================================================================================ + | TEST: IS HIDDEN: RESIDENT BASE TOPIC: INHERITS VALUE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Resolves a topic's reference against an already-resident base topic, and confirms is honored through the base chain once the reference is no longer deferred. + /// + [Fact] + public async Task IsHidden_ResidentBaseTopic_InheritsValue() { + + var records = new StubLazyLoadingTopicRepositoryBuilder() + .AddTopic(211, "Base", "Page", null, indexedAttributes: new Dictionary { ["IsHidden"] = "1" }) + .AddTopic(212, "Derived", "Page", null) + .AddReference(212, "BaseTopic", 211) + .Build(); + + var stub = new StubLazyLoadingTopicRepository(records); + + await stub.Load("Root:Base"); + var derived = await stub.Load("Root:Derived", null, TopicPayload.References); + var rawDerived = (ITopicBackingAccessor)derived!; + + Assert.Empty(rawDerived.References.Deferred); + Assert.True(derived.IsHidden); + Assert.Equal(0, stub.GetFetchCount(211, TopicPayload.ExtendedAttributes)); + + } + /*============================================================================================================================ | TEST: GET URI: INHERITED VALUE: IS RETURNED \---------------------------------------------------------------------------------------------------------------------------*/ From a13cf8ad0a16480b795c4c3276b15e8642665bba Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 28 Jul 2026 16:53:27 -0700 Subject: [PATCH 275/337] Add unit test for auto-loading `BaseTopic` The `BaseTopic` is backed by a reference association and, thus, must fully load references in order to be complete. Unlike other references, this is a key field that must be loaded before even key attributes can be evaluated, since it may inherit from them. While base topics are uncommon outside of the `Configuration` branch, they're nonetheless a critical foundational concept. This test complements the previous test which confirms that a `Topic.Attributes.GetBoolean()` call will traverse a `BaseTopic` without triggering the extended attributes to load (36f6b5f0); this test is the same basic setup, but the `BaseTopic` isn't yet loaded, so it ensures that it's automatically loaded before the attributes can be resolved. --- OnTopic.Tests/TopicReferenceCollectionTest.cs | 37 +++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/OnTopic.Tests/TopicReferenceCollectionTest.cs b/OnTopic.Tests/TopicReferenceCollectionTest.cs index 09847d20..ecb989ac 100644 --- a/OnTopic.Tests/TopicReferenceCollectionTest.cs +++ b/OnTopic.Tests/TopicReferenceCollectionTest.cs @@ -4,8 +4,10 @@ | Project Topics Library \=============================================================================================================================*/ using OnTopic.Associations; +using OnTopic.Repositories; using OnTopic.Tests.Entities; using OnTopic.Collections.Specialized; +using OnTopic.TestDoubles.LazyLoading; using Xunit; namespace OnTopic.Tests; @@ -374,6 +376,41 @@ public void GetTopic_InheritedReferenceWithoutInheritance_ReturnsNull() { } + /*============================================================================================================================ + | TEST: IS HIDDEN: DEFERRED BASE TOPIC: RESOLVES REFERENCE BUT SKIPS EXTENDED ATTRIBUTES + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Reads on a topic whose reference is still deferred (its + /// target was never loaded), and confirms the base topic is resolved so that is still + /// correctly inherited from the base, while the base topic's own extended attributes are never fetched, since IsHidden + /// is an indexed attribute that rides along for free once the base is loaded. + /// + [Fact] + public async Task IsHidden_DeferredBaseTopic_ResolvesReferenceButSkipsExtendedAttributes() { + + var records = new StubLazyLoadingTopicRepositoryBuilder() + .AddTopic(221, "Base", "Page", null, indexedAttributes: new Dictionary { ["IsHidden"] = "1" }) + .AddTopic(222, "Derived", "Page", null) + .AddReference(222, "BaseTopic", 221) + .Build(); + + var stub = new StubLazyLoadingTopicRepository(records); + + // "Base" is never loaded, so its reference stays deferred until something resolves it + var derived = await stub.Load("Root:Derived"); + var rawDerived = (ITopicBackingAccessor)derived!; + + Assert.NotEmpty(rawDerived.References.Deferred); + + // Resolving the base is required, or the topic's key attributes wouldn't even be known: this is a genuine load + Assert.True(derived!.IsHidden); + Assert.Equal(1, stub.GetFetchCount(222, TopicPayload.References)); + + // The base topic's own extended attribute blob is never fetched merely to check an indexed attribute + Assert.Equal(0, stub.GetFetchCount(221, TopicPayload.ExtendedAttributes)); + + } + /*============================================================================================================================ | TEST: ADD: TOPIC REFERENCE WITH BUSINESS LOGIC: IS RETURNED \---------------------------------------------------------------------------------------------------------------------------*/ From 6caac0800698b622761c8b6c0dfb610e61e6143f Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 28 Jul 2026 16:54:22 -0700 Subject: [PATCH 276/337] Remove legacy earmark This was an internal note that shouldn't have been committed. Regardless, it's been superseded with a subsequent plan. --- OnTopic.Data.Caching/CachedTopicRepository.cs | 5 ----- 1 file changed, 5 deletions(-) diff --git a/OnTopic.Data.Caching/CachedTopicRepository.cs b/OnTopic.Data.Caching/CachedTopicRepository.cs index 8f99e9fd..a1b96efe 100644 --- a/OnTopic.Data.Caching/CachedTopicRepository.cs +++ b/OnTopic.Data.Caching/CachedTopicRepository.cs @@ -525,11 +525,6 @@ private void RekeyTopicSubtree(Topic topic, string oldRootUniqueKey) { /// "LazyLoadingTopicRepository.ResolveAssociations(Topic, TopicPayload)"/>), so any relationship or reference targets /// that just became resident are connected without a further trip. /// - /// - /// Interim top-up cost (Stage 1): the gate itself honors precisely, but the underlying still over-fetches a full subtree for any depth - /// ≥ 2 shortfall until Stage 2 wires up a depth-bounded SQL fetch—correct results, interim cost only. - /// /// /// The already-resident topic to confirm or top up. /// The flags the caller requires to be loaded. From 29304b82901ab9f7149735d76c5b56742e92eb55 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 28 Jul 2026 17:36:33 -0700 Subject: [PATCH 277/337] Remove `_reclaimPayload` in concurrency check MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Previously, when implementing the concurrency check in the `CachedTopicRepository` (57792618), I removed the cached `SemaphoreSlim` for the topic once everything _except_ for the `VersionHistory` was loaded. This is because the `VersionHistory` is often not loaded, since it's only needed by the OnTopic Editor in most cases. That said, this introduced potential issues in the case of the editor, this reintroducing the very concurrency issues w were trying to avoid. Since the memory footprint of each `SemaphoreSlim` is trivial relative to the `Topic` it's protecting, I'm removing the `_loadGates` entirely. This also clears the way for reusing it as part of the `Load(…, depth)` (#120, c1e80a53) own concurrency patch (#117), which will reuse it for its own private `EnsureLoaded()` overload. --- OnTopic.Data.Caching/CachedTopicRepository.cs | 20 ------------------- 1 file changed, 20 deletions(-) diff --git a/OnTopic.Data.Caching/CachedTopicRepository.cs b/OnTopic.Data.Caching/CachedTopicRepository.cs index a1b96efe..f176ac5c 100644 --- a/OnTopic.Data.Caching/CachedTopicRepository.cs +++ b/OnTopic.Data.Caching/CachedTopicRepository.cs @@ -34,21 +34,6 @@ public class CachedTopicRepository : TopicRepositoryDecorator, ITopicLazyLoader private readonly object _syncLock = new(); private readonly ConcurrentDictionary _loadGates = new(); - /*============================================================================================================================ - | CONSTANTS - \---------------------------------------------------------------------------------------------------------------------------*/ - - /// - /// Payload whose full load lets a per-topic gate be reclaimed. - /// - /// - /// This excludes , which rarely loads outside the editor, so most gates reclaim as - /// soon as and converge, rather than - /// persisting indefinitely. A gate recreated later for a -only fetch is reclaimed - /// immediately once that fetch completes. - /// - private const TopicPayload _reclaimPayload = TopicPayload.Children | TopicPayload.ExtendedAttributes; - /*============================================================================================================================ | CONSTRUCTOR \---------------------------------------------------------------------------------------------------------------------------*/ @@ -299,11 +284,6 @@ public virtual async Task EnsureLoaded(Topic topic, TopicPayload payload, Cancel gate.Release(); } - // Reclaim: Once ReclaimPayload is loaded, the gate is dead weight, so we can drop the cached instance - if (rawTopic.IsLoaded(_reclaimPayload)) { - _loadGates.TryRemove(new(topic.Id, gate)); - } - } } From 338619e61e5354faedc0c462da47bd1d27901c4b Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 28 Jul 2026 18:02:28 -0700 Subject: [PATCH 278/337] Extend stub gate to support `Load()` MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Yesterday, I introduced the `BlockingStubLazyLoadingTopicRepository` (2875725d) with an `ArmGate()` and `ReleaseGate()` for testing concurrency on the `EnsureLoaded()` method. This extends that by introducing `ArmLoadGate()` and `ReleaseLoadGate()` for testing concurrency issues on the `Load()` method, as well as an accompanying `LoadFetchCount` method. This extends the framework for testing concurrency issues resulting from lazy-loading (#117) and this time in response to the new `Load(…, depth)` implementation (#120). --- .../BlockingStubLazyLoadingTopicRepository.cs | 57 ++++++++++++++++++- 1 file changed, 54 insertions(+), 3 deletions(-) diff --git a/OnTopic.Tests/TestDoubles/BlockingStubLazyLoadingTopicRepository.cs b/OnTopic.Tests/TestDoubles/BlockingStubLazyLoadingTopicRepository.cs index ca8efa42..85e1d79c 100644 --- a/OnTopic.Tests/TestDoubles/BlockingStubLazyLoadingTopicRepository.cs +++ b/OnTopic.Tests/TestDoubles/BlockingStubLazyLoadingTopicRepository.cs @@ -12,9 +12,10 @@ namespace OnTopic.Tests.TestDoubles; | CLASS: BLOCKING STUB LAZY LOADING TOPIC REPOSITORY \-----------------------------------------------------------------------------------------------------------------------------*/ /// -/// A that counts every call and, while "armed", -/// suspends inside it until released, thus letting a test provably interleave two concurrent lazy loads of the same topic -/// without or other timing hacks. +/// A that counts every +/// and call and, while "armed", suspends inside the corresponding one until released, thus +/// letting a test provably interleave two concurrent lazy loads of the same topic without or +/// other timing hacks. /// [ExcludeFromCodeCoverage] internal sealed class BlockingStubLazyLoadingTopicRepository: StubLazyLoadingTopicRepository { @@ -22,8 +23,17 @@ internal sealed class BlockingStubLazyLoadingTopicRepository: StubLazyLoadingTop /*============================================================================================================================ | PRIVATE FIELDS \---------------------------------------------------------------------------------------------------------------------------*/ + private TaskCompletionSource? _loadGate; private TaskCompletionSource? _gate; + /*============================================================================================================================ + | PROPERTY: LOAD FETCH COUNT + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Returns the number of times has been called. + /// + public int LoadFetchCount { get; private set; } + /*============================================================================================================================ | PROPERTY: FETCH COUNT \---------------------------------------------------------------------------------------------------------------------------*/ @@ -32,6 +42,23 @@ internal sealed class BlockingStubLazyLoadingTopicRepository: StubLazyLoadingTop /// public int FetchCount { get; private set; } + /*============================================================================================================================ + | METHOD: ARM LOAD GATE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// "Arms" the gate so the next call suspends until is called. + /// + public void ArmLoadGate() => _loadGate = new(TaskCreationOptions.RunContinuationsAsynchronously); + + /*============================================================================================================================ + | METHOD: RELEASE LOAD GATE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Releases a suspended call "armed" via . + /// + public void ReleaseLoadGate() => _loadGate?.SetResult(); + /*============================================================================================================================ | METHOD: ARM GATE \---------------------------------------------------------------------------------------------------------------------------*/ @@ -48,6 +75,30 @@ internal sealed class BlockingStubLazyLoadingTopicRepository: StubLazyLoadingTop /// public void ReleaseGate() => _gate?.SetResult(); + /*============================================================================================================================ + | METHOD: LOAD + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + public override async Task Load( + int topicId, + Topic? referenceTopic = null, + TopicPayload payload = TopicPayload.None, + int depth = 0 + ) { + + // Record the fetch + LoadFetchCount++; + + // If "armed", suspend until released + if (_loadGate is not null) { + await _loadGate.Task.ConfigureAwait(false); + } + + // Delegate to the base implementation to perform the actual fill + return await base.Load(topicId, referenceTopic, payload, depth).ConfigureAwait(false); + + } + /*============================================================================================================================ | METHODS: TOPIC LAZY LOADER \---------------------------------------------------------------------------------------------------------------------------*/ From 8b56f3cd217d206b897a0783207b1a6dd4212b05 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 28 Jul 2026 18:07:10 -0700 Subject: [PATCH 279/337] Renamed original gates to avoid ambiguity With the introduction of the new `ArmLoadGate()` and `ReleaseLoadGate()` methods and `LoadFetchCount` property (338619e6) on the `BlockingStubLazyLoadingTopicRepository`, the original `ArmGate()` and `ReleaseGate()` methods and `FetchCount` property (2875725d) are ambiguous. To avoid this, rename them explicitly to (The admittedly wordy) `ArmEnsureLoadedGate()`, `ReleaseEnsureLoadedGate()`, and `EnsureLoadedFetchCount`. This refines an effort originally started with #120. --- OnTopic.Tests/CachedTopicRepositoryTest.cs | 6 ++--- .../BlockingStubLazyLoadingTopicRepository.cs | 27 ++++++++++--------- 2 files changed, 17 insertions(+), 16 deletions(-) diff --git a/OnTopic.Tests/CachedTopicRepositoryTest.cs b/OnTopic.Tests/CachedTopicRepositoryTest.cs index 65b14539..e16a6c98 100644 --- a/OnTopic.Tests/CachedTopicRepositoryTest.cs +++ b/OnTopic.Tests/CachedTopicRepositoryTest.cs @@ -244,18 +244,18 @@ public async Task EnsureLoaded_ConcurrentChildrenRequests_FetchesOnceWithoutCorr Assert.False(rawWeb.IsLoaded(TopicPayload.Children)); // "Arm" the gate so the first request suspends mid-fetch, then launch both requests without awaiting either - inner.ArmGate(); + inner.ArmEnsureLoadedGate(); var firstRequest = rawWeb.EnsureLoaded(TopicPayload.Children, CancellationToken); var secondRequest = rawWeb.EnsureLoaded(TopicPayload.Children, CancellationToken); // Release the gate and let both requests run to completion - inner.ReleaseGate(); + inner.ReleaseEnsureLoadedGate(); await Task.WhenAll(firstRequest, secondRequest); // A single inner fetch, no duplicate children, and a fully loaded boundary confirm the race did not corrupt the merge - Assert.Equal(1, inner.FetchCount); + Assert.Equal(1, inner.EnsureLoadedFetchCount); Assert.True(rawWeb.IsLoaded(TopicPayload.Children)); Assert.Equal(2, web.Children.Count); Assert.Equal(2, web.Children.Select(child => child.Id).Distinct().Count()); diff --git a/OnTopic.Tests/TestDoubles/BlockingStubLazyLoadingTopicRepository.cs b/OnTopic.Tests/TestDoubles/BlockingStubLazyLoadingTopicRepository.cs index 85e1d79c..d3f0ef7e 100644 --- a/OnTopic.Tests/TestDoubles/BlockingStubLazyLoadingTopicRepository.cs +++ b/OnTopic.Tests/TestDoubles/BlockingStubLazyLoadingTopicRepository.cs @@ -24,7 +24,7 @@ internal sealed class BlockingStubLazyLoadingTopicRepository: StubLazyLoadingTop | PRIVATE FIELDS \---------------------------------------------------------------------------------------------------------------------------*/ private TaskCompletionSource? _loadGate; - private TaskCompletionSource? _gate; + private TaskCompletionSource? _ensureLoadedGate; /*============================================================================================================================ | PROPERTY: LOAD FETCH COUNT @@ -35,12 +35,12 @@ internal sealed class BlockingStubLazyLoadingTopicRepository: StubLazyLoadingTop public int LoadFetchCount { get; private set; } /*============================================================================================================================ - | PROPERTY: FETCH COUNT + | PROPERTY: ENSURE LOADED FETCH COUNT \---------------------------------------------------------------------------------------------------------------------------*/ /// /// Returns the number of times has been called. /// - public int FetchCount { get; private set; } + public int EnsureLoadedFetchCount { get; private set; } /*============================================================================================================================ | METHOD: ARM LOAD GATE @@ -60,20 +60,21 @@ internal sealed class BlockingStubLazyLoadingTopicRepository: StubLazyLoadingTop public void ReleaseLoadGate() => _loadGate?.SetResult(); /*============================================================================================================================ - | METHOD: ARM GATE + | METHOD: ARM ENSURE LOADED GATE \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// "Arms" the gate so the next call suspends until is called. + /// "Arms" the gate so the next call suspends until is + /// called. /// - public void ArmGate() => _gate = new(TaskCreationOptions.RunContinuationsAsynchronously); + public void ArmEnsureLoadedGate() => _ensureLoadedGate = new(TaskCreationOptions.RunContinuationsAsynchronously); /*============================================================================================================================ - | METHOD: RELEASE GATE + | METHOD: RELEASE ENSURE LOADED GATE \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Releases a suspended call "armed" via . + /// Releases a suspended call "armed" via . /// - public void ReleaseGate() => _gate?.SetResult(); + public void ReleaseEnsureLoadedGate() => _ensureLoadedGate?.SetResult(); /*============================================================================================================================ | METHOD: LOAD @@ -100,17 +101,17 @@ internal sealed class BlockingStubLazyLoadingTopicRepository: StubLazyLoadingTop } /*============================================================================================================================ - | METHODS: TOPIC LAZY LOADER + | METHODS: ENSURE LOADED \---------------------------------------------------------------------------------------------------------------------------*/ /// public override async Task EnsureLoaded(Topic topic, TopicPayload payload, CancellationToken cancellationToken = default) { // Record the fetch - FetchCount++; + EnsureLoadedFetchCount++; // If "armed", suspend until released - if (_gate is not null) { - await _gate.Task.ConfigureAwait(false); + if (_ensureLoadedGate is not null) { + await _ensureLoadedGate.Task.ConfigureAwait(false); } // Delegate to the base implementation to perform the actual fill From 5840f011a2719acaed1518c83efd0163b66d7c4a Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 28 Jul 2026 18:18:01 -0700 Subject: [PATCH 280/337] Added unit test to validate concurrency bug MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Building off of the addition of `ArmLoadGate()`, `ReleaseLoadGate()`, and `LoadFetchCount` on the `BlockingStubLazyLoadingTopicRepository` (338619e6), introduced a new unit test to trigger concurrency on `Load()` and ensure that the data is not corrupted, thus laying the foundation for the concurrency updates (#117) that address potential issues introduced by the lazy-loading infrastructure (#111) and the introduction of `Load(…, depth)` (#120). This will fail for now, until the core concurrency bug is resolved in a subsequent commit. This complements the earlier test that was introduced to test `EnsureLoaded()` (14fb36e5, 8b56f3cd). --- OnTopic.Tests/CachedTopicRepositoryTest.cs | 50 ++++++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/OnTopic.Tests/CachedTopicRepositoryTest.cs b/OnTopic.Tests/CachedTopicRepositoryTest.cs index e16a6c98..3a293abd 100644 --- a/OnTopic.Tests/CachedTopicRepositoryTest.cs +++ b/OnTopic.Tests/CachedTopicRepositoryTest.cs @@ -218,6 +218,56 @@ public async Task TaskEnsureLoaded_DeferredAssociationFallbackWithResidentTarget } + /*============================================================================================================================ + | TEST: LOAD: CONCURRENT DEPTH TOP-UP REQUESTS: FETCHES ONCE WITHOUT CORRUPTION + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Reproduces a concurrent-read race on a common topic that is loaded, but has a shallower depth than is being + /// requested: Two concurrent depth-aware + /// requests for the same cached topic must deep-load and merge exactly once, not twice, into the shared subtree. + /// + /// + /// Uses , which suspends inside its own Load until released, to + /// interleave both requests without any or other timing hack, exactly as does for the payload-only gate. Requests + /// depth: -1 rather than a finite depth: A finite-depth Load() only ever agrees with one tier shallower than requested (see ), so a finite-depth waiter's gate check would + /// never observe sufficiency and would always reissue a redundant fetch, an unrelated, pre-existing asymmetry this test + /// must avoid. + /// + [Fact] + public async Task Load_ConcurrentDepthTopUpRequests_FetchesOnceWithoutCorruption() { + + var inner = new BlockingStubLazyLoadingTopicRepository(); + var cache = new CachedTopicRepository(inner); + var web = await cache.Load("Web"); + var rawWeb = (ITopicLazyLoadable)web!; + + Assert.False(rawWeb.IsLoaded(TopicPayload.Children)); + + // Baseline excludes the constructor's own "Root" and "Root:Configuration" fetches against the inner repository + var baselineFetchCount = inner.LoadFetchCount; + + // "Arm" the load gate so the first request suspends mid-fetch, then launch both requests without awaiting either + inner.ArmLoadGate(); + + var firstRequest = cache.Load(web!.Id, payload: TopicPayload.Children, depth: -1); + var secondRequest = cache.Load(web!.Id, payload: TopicPayload.Children, depth: -1); + + // Release the gate and let both requests run to completion + inner.ReleaseLoadGate(); + + await Task.WhenAll(firstRequest, secondRequest); + + // A single inner deep fetch, no duplicate children, and a fully loaded subtree confirm the race did not corrupt the merge + Assert.Equal(1, inner.LoadFetchCount - baselineFetchCount); + Assert.True(rawWeb.IsLoaded(TopicPayload.Children, depth: -1)); + Assert.Equal(2, web.Children.Count); + Assert.Equal(2, web.Children.Select(child => child.Id).Distinct().Count()); + + } + /*============================================================================================================================ | TEST: ENSURE LOADED: CONCURRENT CHILDREN REQUESTS: FETCHES ONCE WITHOUT CORRUPTION \---------------------------------------------------------------------------------------------------------------------------*/ From 843016d6a9f66ac3001d26b99fbcdd5d7459b814 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 28 Jul 2026 19:21:14 -0700 Subject: [PATCH 281/337] Introduced `WithLoadGate<>()` helpers MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Previously, I introduced a topic-based concurrency gate to the (public implementation of the) `EnsureLoaded()` method (57792618), as part of the concurrency response (#117) to the lazy-loading implementation (#111). With the new `Load(…, depth)` implementation (#120), there are additional concurrency issues exposed, which will require additional gates. The `WithLoadGate<>()` methods allow that to be centralized. --- OnTopic.Data.Caching/CachedTopicRepository.cs | 85 ++++++++++++++++--- 1 file changed, 75 insertions(+), 10 deletions(-) diff --git a/OnTopic.Data.Caching/CachedTopicRepository.cs b/OnTopic.Data.Caching/CachedTopicRepository.cs index f176ac5c..0b065711 100644 --- a/OnTopic.Data.Caching/CachedTopicRepository.cs +++ b/OnTopic.Data.Caching/CachedTopicRepository.cs @@ -270,19 +270,15 @@ public virtual async Task EnsureLoaded(Topic topic, TopicPayload payload, Cancel if (innerPayload is not TopicPayload.None) { // Serialize fetches and merges (children, extended attributes, version history) per topic - var gate = _loadGates.GetOrAdd(topic.Id, _ => new(1, 1)); - await gate.WaitAsync(cancellationToken).ConfigureAwait(false); - try { + await WithLoadGate(_loadGates, topic.Id, async () => { // Second escape hatch: Re-filter under the gate, since a prior holder may have merged some or all of this payload - innerPayload = rawTopic.FilterPayload(innerPayload); - if (innerPayload is not TopicPayload.None) { - await loader.EnsureLoaded(topic, innerPayload, cancellationToken).ConfigureAwait(false); + var remainingPayload = rawTopic.FilterPayload(innerPayload); + if (remainingPayload is not TopicPayload.None) { + await loader.EnsureLoaded(topic, remainingPayload, cancellationToken).ConfigureAwait(false); } - } - finally { - gate.Release(); - } + + }, cancellationToken).ConfigureAwait(false); } } @@ -546,4 +542,73 @@ int depth } + /*============================================================================================================================ + | METHOD: WITH LOAD GATE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Serializes against any other in-flight call sharing in , via a persistent, per-key acquired before, and released after, runs. + /// + /// + /// Shared by every concurrency gate with the same identity in this class: Each supplies its own sufficiency check and load + /// logic via , since that varies by call site, while this method owns only the acquire and + /// release ceremony common to all of them. + /// + /// + /// The per-key gate dictionary to acquire 's from. + /// + /// The identity to serialize concurrent calls against. + /// The sufficiency check and load logic to run once the gate is acquired. + /// An optional token that can cancel waiting on the gate itself. + private static async Task WithLoadGate( + ConcurrentDictionary gates, + TKey key, + Func> execute, + CancellationToken cancellationToken = default + ) where TKey: notnull { + + // Ensure the gate is established + var gate = gates.GetOrAdd(key, _ => new(1, 1)); + await gate.WaitAsync(cancellationToken).ConfigureAwait(false); + + // Execute the action + try { + return await execute().ConfigureAwait(false); + } + + // Release the gate + finally { + gate.Release(); + } + + } + + /// + /// + /// for gated work that requires a return ; this one does not. + /// + private static async Task WithLoadGate( + ConcurrentDictionary gates, + TKey key, + Func execute, + CancellationToken cancellationToken = default + ) where TKey: notnull { + + // Ensure the gate is established + var gate = gates.GetOrAdd(key, _ => new(1, 1)); + await gate.WaitAsync(cancellationToken).ConfigureAwait(false); + + // Execute the action + try { + await execute().ConfigureAwait(false); + } + + // Release the gate + finally { + gate.Release(); + } + + } + } //Class \ No newline at end of file From 5197006b428978a0d2b047a8b524a101d91d1f50 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 28 Jul 2026 19:47:55 -0700 Subject: [PATCH 282/337] Added private `EnsureLoaded()` concurrency gate per topic MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit While multiple topics can lazy load their members concurrently, the private `EnsureLoaded(Topic, TopicPayload, Int32)` — used internally by `Load(Int32, Topic?, TopicPayload, Int32)` to top up an already-resident topic — should only operate against a single topic at a time, thus avoiding potential concurrency issues or corrupted data. This rechecks the topic against `IsLoaded()` under the gate before loading, so a waiter skips a now-redundant fetch that a prior holder already satisfied. This provides a follow-up fix for the concurrency updates (#117) to the lazy-loading infrastructure (#111) as newly introduced by the `Load(…, depth)` (#120) implementation. Associations will be handled in a future commit. This complements the original implementation for the (public) `EnsureLoaded()` (57792618). This applies to the (private) `EnsureLoaded()` that's exclusively used by `Load()`, and uses the same newly introduced `WithLoadGate<>()` helper (843016d6). --- OnTopic.Data.Caching/CachedTopicRepository.cs | 30 +++++++++++++------ 1 file changed, 21 insertions(+), 9 deletions(-) diff --git a/OnTopic.Data.Caching/CachedTopicRepository.cs b/OnTopic.Data.Caching/CachedTopicRepository.cs index 0b065711..759b0d98 100644 --- a/OnTopic.Data.Caching/CachedTopicRepository.cs +++ b/OnTopic.Data.Caching/CachedTopicRepository.cs @@ -497,9 +497,12 @@ private void RekeyTopicSubtree(Topic topic, string oldRootUniqueKey) { /// />, which converges LoadState in a single batched round-trip. Any other shortfall, including a whole-tree /// request, performs one deep against the /// underlying repository, using itself as the reference into the topic graph, so the underlying - /// load merges the result directly into it. It then looks up any in-graph associations (), so any relationship or reference targets - /// that just became resident are connected without a further trip. + /// load merges the result directly into it. This deep load is serialized per topic via the same + /// gate as , since both mutate the same 's collections and must not merge concurrently; a double-checked re-read under the gate lets a waiter skip a + /// now-redundant fetch a prior load already satisfied. It then looks up any in-graph associations outside the gate (), so any relationships or references + /// that were just loaded are connected without a further trip. /// /// /// The already-resident topic to confirm or top up. @@ -515,21 +518,30 @@ int depth var gate = payload & ~(TopicPayload.Relationships | TopicPayload.References); // Return immediately if the resident topic already satisfies the requested scope - if (((ITopicLazyLoadable)topic).IsLoaded(gate, depth)) { + var rawTopic = (ITopicLazyLoadable)topic; + if (rawTopic.IsLoaded(gate, depth)) { return; } // Top up a single-topic shortfall via the loader, which converges LoadState in a single round-trip if (depth is 0) { - await ((ITopicLazyLoadable)topic).EnsureLoaded(gate).ConfigureAwait(false); + await rawTopic.EnsureLoaded(gate).ConfigureAwait(false); return; } - // Top up any other shortfall via one deep load, merged into the live graph - var loaded = await TopicRepository - .Load(topic.Id, topic, payload, depth) - .ConfigureAwait(false); + // Top-up any other shortfall via one deep load, serialized per topic to prevent concurrent same-topic merges + var loaded = await WithLoadGate(_loadGates, topic.Id, async () => { + + // Second escape hatch: A prior holder may have already merged this (or a deeper) region under the gate + if (rawTopic.IsLoaded(gate, depth)) { + return null; + } + return await TopicRepository.Load(topic.Id, topic, payload, depth).ConfigureAwait(false); + + }).ConfigureAwait(false); + // Resolve associations outside the gate; a waiter that returned at the double-check gate relies on the first holder's + // resolution (of the same or a deeper region) or the normal deferred lazy-load, since associations are not gated if (loaded is not null) { // Opportunistically connect any relationship or reference targets that are now resident in the merged region, regardless From a617b24c6710330aa69852ac0de63497e38195d7 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 28 Jul 2026 20:16:28 -0700 Subject: [PATCH 283/337] Added `Load(topicId)` concurrency gate per topic MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit While multiple topics can lazy load their members concurrently, `Load(topicId)` should only operate against a single topic at a time, thus avoiding potential concurrency issues or corrupted data. This rechecks the `TopicPayload` against `IsLoaded()` after the gate is released to avoid retrieving the same data that a previous request just loaded. This is noisier than I'd prefer since it needs to redo the check for the existing item (obviously) but also the missing index, plus (re)adding the item to the index. That said, I was at least able to place some of this in the shared `GetPreviousLoad()` helper, which determines if there was a previous attempt to load the topic and, if so, whether it was successful. This provides a follow-up fix for the concurrency updates (#117) to the lazy-loading infrastructure (#111) as newly introduced by the `Load(…, depth)` (#120) implementation. Associations will be handled in a future commit. This complements the original implementation for the (public) `EnsureLoaded()` (57792618) and `Load(uniqueKey)` (1e8dd7c4). This applies to the (private) `EnsureLoaded()` that's exclusively used by `Load()`, and uses the same newly introduced `WithLoadGate<>()` helper (843016d6). --- OnTopic.Data.Caching/CachedTopicRepository.cs | 98 ++++++++++++++----- 1 file changed, 72 insertions(+), 26 deletions(-) diff --git a/OnTopic.Data.Caching/CachedTopicRepository.cs b/OnTopic.Data.Caching/CachedTopicRepository.cs index 759b0d98..9dc42297 100644 --- a/OnTopic.Data.Caching/CachedTopicRepository.cs +++ b/OnTopic.Data.Caching/CachedTopicRepository.cs @@ -101,8 +101,11 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos /// insufficient hit is topped up via before being returned. On a /// miss, falls through to the underlying repository with @LoadAscendants enabled so the full ancestor chain is /// fetched and merged into the live graph, using if supplied, or the cache root - /// otherwise, so the underlying load seeds its working index from, and can attach directly to, the resident graph. Missing - /// IDs are recorded to prevent redundant round-trips for topics that do not exist. + /// otherwise, so the underlying load seeds its working index from, and can attach directly to, the referenced graph. This + /// fall-through is serialized per via the same gate the hit path uses, + /// with a double-checked re-read of both the live index and the Missing ID index under the gate, so concurrent requests for + /// the same uncached ID merge exactly once rather than racing. Missing IDs are recorded to prevent redundant round-trips + /// for topics that do not exist. /// public override async Task Load( int topicId, @@ -120,41 +123,56 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos } /*-------------------------------------------------------------------------------------------------------------------------- - | Lookup by topic identifier; top up and return on a hit + | Lookup by topic identifier; top up and return on a hit, or skip a known miss, before falling through to a fresh load \-------------------------------------------------------------------------------------------------------------------------*/ - _cache.GetLiveTopicIndex().TryGetValue(topicId, out var topic); - if (topic is not null) { - await EnsureLoaded(topic, payload, depth).ConfigureAwait(false); - return topic; + var (resident, isAbsent) = GetPreviousLoad(topicId); + + if (resident is not null) { + await EnsureLoaded(resident, payload, depth).ConfigureAwait(false); + return resident; + } + + if (isAbsent) { + return null; } /*-------------------------------------------------------------------------------------------------------------------------- - | Skip IDs that are known to be missing to avoid redundant round-trips + | On miss: Load with ancestors and merge result into the live graph, serialized per ID to prevent concurrent per-topic loads \-------------------------------------------------------------------------------------------------------------------------*/ - lock (_syncLock) { - if (_absentTopicIdIndex.Contains(topicId)) { + return await WithLoadGate(_loadGates, topicId, async () => { + + // Second escape hatch: A prior holder may have loaded this ID, or recorded a miss, while this thread waited + var (existingTopic, existingIsAbsent) = GetPreviousLoad(topicId); + + // Return match + if (existingTopic is not null) { + var gate = payload & ~(TopicPayload.Relationships | TopicPayload.References); + if (((ITopicLazyLoadable)existingTopic).IsLoaded(gate, depth)) { + return existingTopic; + } + } + + // If there was a previous load attempt, return early + else if (existingIsAbsent) { return null; } - } - /*-------------------------------------------------------------------------------------------------------------------------- - | On miss: Load with ancestors and merge result into the live graph - \-------------------------------------------------------------------------------------------------------------------------*/ - var loaded = await TopicRepository - .Load(topicId, referenceTopic?? _cache, payload, depth) - .ConfigureAwait(false); + // Insufficient? Load with ancestors and merge into whichever instance is already available, if any + var freshlyLoaded = await TopicRepository + .Load(topicId, existingTopic?? referenceTopic?? _cache, payload, depth) + .ConfigureAwait(false); - // If it's missing, populate the appropriate index so we don't try loading it again - if (loaded is null) { - lock (_syncLock) { - _absentTopicIdIndex.Add(topicId); + // If it's missing, populate the index so we don't try loading it again + if (freshlyLoaded is null) { + lock (_syncLock) { + _absentTopicIdIndex.Add(topicId); + } } - return null; - } - // Return the topic from the cache; the TopicIndexRegistry hooks indexed it as it was merged above - _cache.GetLiveTopicIndex().TryGetValue(topicId, out var result); - return result; + // Return the loaded topic, if present + return freshlyLoaded; + + }).ConfigureAwait(false); } @@ -554,6 +572,34 @@ int depth } + /*============================================================================================================================ + | METHOD: GET PREVIOUS LOAD + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Looks up in the live index and, on a miss, reports whether it was previously recorded as + /// absent. + /// + /// + /// Centralizes the lookup mechanics shared by 's pre- and post-gate + /// checks; each caller still decides for itself what a hit, a miss, or a recorded absence means at that point in the flow. + /// + private (Topic? Resident, bool IsAbsent) GetPreviousLoad(int topicId) { + + // Attempt to lookup the item + _cache.GetLiveTopicIndex().TryGetValue(topicId, out var resident); + + // If it's found report that + if (resident is not null) { + return (resident, false); + } + + // Otherwise, report of it's already reported as missing + lock (_syncLock) { + return (null, _absentTopicIdIndex.Contains(topicId)); + } + + } + /*============================================================================================================================ | METHOD: WITH LOAD GATE \---------------------------------------------------------------------------------------------------------------------------*/ From c3df4a82a8804e27c4a9c6535c1dc4ff6d2a1ca9 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 28 Jul 2026 20:42:34 -0700 Subject: [PATCH 284/337] Added unit test for `Load(topicId)` concurrency MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This provides a unit test for the recently introduced concurrency check added to `Load(topicId, …, depth)` (d9f1b623), which addresses new concurrency issues introduced by the interplay of lazy-loading (#111) and the new `Load(…, depth)` capabilities (#120). This fills a gap in the concurrency and testings of the lazy-loading (#117). --- OnTopic.Tests/CachedTopicRepositoryTest.cs | 45 ++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/OnTopic.Tests/CachedTopicRepositoryTest.cs b/OnTopic.Tests/CachedTopicRepositoryTest.cs index 3a293abd..1cd90ee2 100644 --- a/OnTopic.Tests/CachedTopicRepositoryTest.cs +++ b/OnTopic.Tests/CachedTopicRepositoryTest.cs @@ -268,6 +268,51 @@ public async Task Load_ConcurrentDepthTopUpRequests_FetchesOnceWithoutCorruption } + /*============================================================================================================================ + | TEST: LOAD: CONCURRENT COLD MISS REQUESTS: FETCHES ONCE WITHOUT CORRUPTION + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Reproduces a concurrent-read race on the same topicId that hasn't yet been loaded: Two concurrent requests for the same uncached ID must deep-load and + /// merge exactly once, not twice, into the shared cache graph, and both callers must resolve to the same attached instance. + /// + /// + /// Uses the , which suspends inside its own Load until released, + /// to interleave both requests without any or other timing hack, exactly as does for the depth gate. Requests depth: -1 + /// for the same reason that test does: A finite-depth request would never agree with the gated check from . + /// + [Fact] + public async Task Load_ConcurrentColdMissRequests_FetchesOnceWithoutCorruption() { + + var inner = new BlockingStubLazyLoadingTopicRepository(); + var cache = new CachedTopicRepository(inner); + + // Baseline excludes the constructor's own "Root" and "Root:Configuration" fetches against the inner repository + var baselineFetchCount = inner.LoadFetchCount; + + // "Arm" the load gate so the first request suspends mid-fetch, then launch both requests without awaiting either + inner.ArmLoadGate(); + + // "Web_0_0" (id 10002) is not yet resident: Only "Root", "Root:Configuration", and "Web" are seeded by the constructor + var firstRequest = cache.Load(10002, payload: TopicPayload.Children, depth: -1); + var secondRequest = cache.Load(10002, payload: TopicPayload.Children, depth: -1); + + // Release the gate and let both requests run to completion + inner.ReleaseLoadGate(); + + var (first, second) = (await firstRequest, await secondRequest); + + // A single inner fetch, and the same resident instance returned to both callers, confirming the race did not corrupt the + // merge + Assert.Equal(1, inner.LoadFetchCount - baselineFetchCount); + Assert.NotNull(first); + Assert.Same(first, second); + Assert.Equal("Web_0_0", first!.Key); + + } + /*============================================================================================================================ | TEST: ENSURE LOADED: CONCURRENT CHILDREN REQUESTS: FETCHES ONCE WITHOUT CORRUPTION \---------------------------------------------------------------------------------------------------------------------------*/ From 4c82c4a3052d6e6ab8469935a3166fd13f893cca Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 28 Jul 2026 21:09:18 -0700 Subject: [PATCH 285/337] Added `Load(uniqueKey)` concurrency gate per topic MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit While multiple topics can lazy load their members concurrently, `Load(uniqueKey)` should only operate against a single topic at a time, thus avoiding potential concurrency issues or corrupted data, especially during initial site loads where popular pages will be getting a lot of requests. This rechecks the `TopicPayload` against `IsLoaded()` after the gate is released to avoid retrieving the same data that a previous request just loaded. This is noisier than I'd prefer since it needs to redo the check for the existing item (obviously) but also the missing index, plus (re)adding the item to the index. That said, I was at least able to place some of this in the shared `GetPreviousLoad()` overload, which determines if there was a previous attempt to load the topic and, if so, whether it was successful. This provides a follow-up fix for the concurrency updates (#117) to the lazy-loading infrastructure (#111) as newly introduced by the `Load(…, depth)` (#120) implementation. Associations will be handled in a future commit. This complements the original implementation for the (public) `EnsureLoaded()` (57792618), the private `EnsureLoaded()` (5197006b), and `Load(topicId)` (a617b24c). This applies to the (private) `EnsureLoaded()` that's exclusively used by `Load()`, and uses the same newly introduced `WithLoadGate<>()` helper (843016d6). --- OnTopic.Data.Caching/CachedTopicRepository.cs | 93 +++++++++++++------ 1 file changed, 66 insertions(+), 27 deletions(-) diff --git a/OnTopic.Data.Caching/CachedTopicRepository.cs b/OnTopic.Data.Caching/CachedTopicRepository.cs index 9dc42297..66ef3274 100644 --- a/OnTopic.Data.Caching/CachedTopicRepository.cs +++ b/OnTopic.Data.Caching/CachedTopicRepository.cs @@ -33,6 +33,7 @@ public class CachedTopicRepository : TopicRepositoryDecorator, ITopicLazyLoader private readonly HashSet _absentUniqueKeyIndex = new(StringComparer.OrdinalIgnoreCase); private readonly object _syncLock = new(); private readonly ConcurrentDictionary _loadGates = new(); + private readonly ConcurrentDictionary _keyLoadGates = new(StringComparer.OrdinalIgnoreCase); /*============================================================================================================================ | CONSTRUCTOR @@ -182,8 +183,10 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos /// insufficient hit is topped up via before being returned. On a /// miss, falls through to the underlying repository with @LoadAscendants enabled so the full ancestor chain is /// fetched and merged into the live graph, using if supplied, or the cache root - /// otherwise, so the underlying load seeds its working index from, and can attach directly to, the resident graph. Missing - /// IDs are recorded to prevent redundant round-trips for topics that do not exist. + /// otherwise, so the underlying load seeds its working index from, and can attach directly to, the resident graph. This + /// fall-through is serialized per via , with a double-checked + /// reread of both the key and the missing-key index under the gate, so concurrent requests for the same uncached key merge + /// exactly once. Missing keys are recorded to prevent redundant round-trips for topics that do not exist. /// public override async Task Load( string uniqueKey, @@ -210,45 +213,57 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos } /*-------------------------------------------------------------------------------------------------------------------------- - | Lookup by unique key; top up and return on a hit + | Lookup by unique key; top up and return on a hit, or skip a known miss, before falling through to a fresh load \-------------------------------------------------------------------------------------------------------------------------*/ - Topic? resident; - lock (_syncLock) { - _topicKeyIndex.TryGetValue(uniqueKey, out resident); - } + var (resident, isAbsent) = GetPreviousLoad(uniqueKey); + if (resident is not null) { await EnsureLoaded(resident, payload, depth).ConfigureAwait(false); return resident; } + if (isAbsent) { + return null; + } + /*-------------------------------------------------------------------------------------------------------------------------- - | Skip IDs that are known to be missing to avoid redundant round-trips + | On miss: Load with ancestors and merge result into the live graph, serialized per key to prevent concurrent loads for the + | same uncached uniqueKey \-------------------------------------------------------------------------------------------------------------------------*/ - lock (_syncLock) { - if (_absentUniqueKeyIndex.Contains(uniqueKey)) { + return await WithLoadGate(_keyLoadGates, uniqueKey, async () => { + + // Second escape hatch: A prior holder may have loaded this key, or recorded a miss, while this thread waited + var (existingTopic, existingIsAbsent) = GetPreviousLoad(uniqueKey); + + // Return match + if (existingTopic is not null) { + var gate = payload & ~(TopicPayload.Relationships | TopicPayload.References); + if (((ITopicLazyLoadable)existingTopic).IsLoaded(gate, depth)) { + return existingTopic; + } + } + + // If there was a previous load attempt, return early + else if (existingIsAbsent) { return null; } - } - /*-------------------------------------------------------------------------------------------------------------------------- - | On miss: Load with ancestors and merge result into the live graph - \-------------------------------------------------------------------------------------------------------------------------*/ - var loaded = await TopicRepository - .Load(uniqueKey, referenceTopic?? _cache, payload, depth) - .ConfigureAwait(false); + // Insufficient? Load with ancestors and merge into whichever instance is already available, if any + var freshlyLoaded = await TopicRepository + .Load(uniqueKey, existingTopic?? referenceTopic?? _cache, payload, depth) + .ConfigureAwait(false); - if (loaded is null) { - lock (_syncLock) { - _absentUniqueKeyIndex.Add(uniqueKey); + // If it's missing, populate the index so we don't try loading it again + if (freshlyLoaded is null) { + lock (_syncLock) { + _absentUniqueKeyIndex.Add(uniqueKey); + } } - return null; - } - // Return the topic from the cache - lock (_syncLock) { - _topicKeyIndex.TryGetValue(uniqueKey, out var result); - return result; - } + // Return the loaded topic, if present + return freshlyLoaded; + + }).ConfigureAwait(false); } @@ -600,6 +615,30 @@ int depth } + /// + /// Looks up in the key index and, on a miss, reports whether it was previously recorded as + /// absent. + /// + /// + /// Centralizes the lookup mechanics shared by 's pre- and post-gate + /// checks; each caller still decides for itself what a hit, a miss, or a recorded absence means at that point in the flow. + /// Assumes has already been normalized to its canonical form. Unlike its counterpart, both checks share one block, since —a plain , not the lock-free the id + /// overload reads from—isn't safe to read without it. + /// + private (Topic? Resident, bool IsAbsent) GetPreviousLoad(string uniqueKey) { + + // Attempt to lookup the item + lock (_syncLock) { + if (_topicKeyIndex.TryGetValue(uniqueKey, out var resident)) { + return (resident, false); + } + return (null, _absentUniqueKeyIndex.Contains(uniqueKey)); + } + + } + /*============================================================================================================================ | METHOD: WITH LOAD GATE \---------------------------------------------------------------------------------------------------------------------------*/ From fe76592b00038b373b15607093c3a5d85a9e55b8 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 28 Jul 2026 21:15:06 -0700 Subject: [PATCH 286/337] Added unit test for `Load(uniqueKey)` concurrency MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This provides a unit test for the recently introduced concurrency check added to `Load(uniqueKey, …, depth)` (4c82c4a3), which addresses new concurrency issues introduced by the interplay of lazy-loading (#111) and the new `Load(…, depth)` capabilities (#120). This fills a gap in the concurrency and testings of the lazy-loading (#117). This corresponds to the similar update (d9f1b623) and test (c3df4a82) for `Load(topicId)`. As part of this, I clarified the name of the prior test to make sure it was unambiguous compared to this new one. --- OnTopic.Tests/CachedTopicRepositoryTest.cs | 49 +++++++++++++++++++++- 1 file changed, 47 insertions(+), 2 deletions(-) diff --git a/OnTopic.Tests/CachedTopicRepositoryTest.cs b/OnTopic.Tests/CachedTopicRepositoryTest.cs index 1cd90ee2..82c14743 100644 --- a/OnTopic.Tests/CachedTopicRepositoryTest.cs +++ b/OnTopic.Tests/CachedTopicRepositoryTest.cs @@ -269,7 +269,7 @@ public async Task Load_ConcurrentDepthTopUpRequests_FetchesOnceWithoutCorruption } /*============================================================================================================================ - | TEST: LOAD: CONCURRENT COLD MISS REQUESTS: FETCHES ONCE WITHOUT CORRUPTION + | TEST: LOAD: CONCURRENT COLD MISS REQUESTS (BY ID): FETCHES ONCE WITHOUT CORRUPTION \---------------------------------------------------------------------------------------------------------------------------*/ /// /// Reproduces a concurrent-read race on the same topicId that hasn't yet been loaded: Two concurrent . /// [Fact] - public async Task Load_ConcurrentColdMissRequests_FetchesOnceWithoutCorruption() { + public async Task Load_ConcurrentColdMissByIdRequests_FetchesOnceWithoutCorruption() { var inner = new BlockingStubLazyLoadingTopicRepository(); var cache = new CachedTopicRepository(inner); @@ -313,6 +313,51 @@ public async Task Load_ConcurrentColdMissRequests_FetchesOnceWithoutCorruption() } + /*============================================================================================================================ + | TEST: LOAD: CONCURRENT COLD MISS REQUESTS (BY KEY): FETCHES ONCE WITHOUT CORRUPTION + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Reproduces a concurrent-read race on the same normalized uniqueKey that hasn't yet been loaded: Two concurrent + /// requests for the same uncached key must + /// deep-load and merge exactly once, not twice, into the shared cache graph, and both callers must resolve to the same + /// attached instance. + /// + /// + /// Uses the , exactly as does for the topicId gate. Requests + /// depth: -1 for the same reason that test does: A finite-depth request would never agree with the gated check from + /// . + /// + [Fact] + public async Task Load_ConcurrentColdMissByKeyRequests_FetchesOnceWithoutCorruption() { + + var inner = new BlockingStubLazyLoadingTopicRepository(); + var cache = new CachedTopicRepository(inner); + + // Baseline excludes the constructor's own "Root" and "Root:Configuration" fetches against the inner repository + var baselineFetchCount = inner.LoadFetchCount; + + // "Arm" the load gate so the first request suspends mid-fetch, then launch both requests without awaiting either + inner.ArmLoadGate(); + + // "Web_0_0" is not yet resident: Only "Root", "Root:Configuration", and "Web" are seeded by the constructor + var firstRequest = cache.Load("Web:Web_0:Web_0_0", payload: TopicPayload.Children, depth: -1); + var secondRequest = cache.Load("Web:Web_0:Web_0_0", payload: TopicPayload.Children, depth: -1); + + // Release the gate and let both requests run to completion + inner.ReleaseLoadGate(); + + var (first, second) = (await firstRequest, await secondRequest); + + // A single inner fetch, and the same resident instance returned to both callers, confirming the race did not corrupt the + // merge + Assert.Equal(1, inner.LoadFetchCount - baselineFetchCount); + Assert.NotNull(first); + Assert.Same(first, second); + Assert.Equal("Web_0_0", first!.Key); + + } + /*============================================================================================================================ | TEST: ENSURE LOADED: CONCURRENT CHILDREN REQUESTS: FETCHES ONCE WITHOUT CORRUPTION \---------------------------------------------------------------------------------------------------------------------------*/ From 78585b4746aeca8dcc405e6423fc5ef454059140 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Wed, 29 Jul 2026 13:46:27 -0700 Subject: [PATCH 287/337] Document concurrency limitations MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit While I've covered the most obvious and common concurrency scenarios (#117), there remain gaps left behind by the move to lazy loading (#111) and, to a lesser degree, `Load(…, depth)` (#120). This at least documents those cases to aid in discoverability so that consumers understand the concurrency limitations. --- OnTopic.Data.Caching/CachedTopicRepository.cs | 11 +++++++++++ OnTopic/Repositories/ITopicRepository.cs | 18 ++++++++++++++---- 2 files changed, 25 insertions(+), 4 deletions(-) diff --git a/OnTopic.Data.Caching/CachedTopicRepository.cs b/OnTopic.Data.Caching/CachedTopicRepository.cs index 66ef3274..0ec3c0ae 100644 --- a/OnTopic.Data.Caching/CachedTopicRepository.cs +++ b/OnTopic.Data.Caching/CachedTopicRepository.cs @@ -107,6 +107,12 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos /// with a double-checked re-read of both the live index and the Missing ID index under the gate, so concurrent requests for /// the same uncached ID merge exactly once rather than racing. Missing IDs are recorded to prevent redundant round-trips /// for topics that do not exist. + /// + /// This only covers duplicates with the same identity; it does not extend to concurrent loads that merge into + /// overlapping regions of the graph under different identities (e.g., an ancestor and one of its not-yet-loaded + /// descendants). See for the full concurrency + /// contract. + /// /// public override async Task Load( int topicId, @@ -187,6 +193,11 @@ public CachedTopicRepository(ITopicRepository topicRepository) : base(topicRepos /// fall-through is serialized per via , with a double-checked /// reread of both the key and the missing-key index under the gate, so concurrent requests for the same uncached key merge /// exactly once. Missing keys are recorded to prevent redundant round-trips for topics that do not exist. + /// + /// This only covers same-identity duplicates; it does not extend to concurrent loads that merge into overlapping + /// regions under different identities. See for + /// the full concurrency contract. + /// /// public override async Task Load( string uniqueKey, diff --git a/OnTopic/Repositories/ITopicRepository.cs b/OnTopic/Repositories/ITopicRepository.cs index d88cda3b..0b5401d8 100644 --- a/OnTopic/Repositories/ITopicRepository.cs +++ b/OnTopic/Repositories/ITopicRepository.cs @@ -111,6 +111,14 @@ public interface ITopicRepository { /// the seed topic; N loads N tiers of descendants. Ancestor topics are always loaded when needed to place /// the seed topic within the graph. /// + /// + /// Concurrent calls that merge into overlapping regions of the same graph are not + /// guaranteed to be thread-safe: Implementors may serialize duplicate requests for the same identity (i.e., the same + /// or uniqueKey), but a broader, cross-region lock over the graph is not part of this + /// contract. Callers performing an eager or whole-tree warm (depth: -1) against a shared graph should do so in a + /// single threaded, typically during startup, after which the warmed region is effectively read-only and safe for + /// concurrent reads. + /// /// A topic object. Task Load( int topicId, @@ -129,12 +137,14 @@ public interface ITopicRepository { /// associations—such as references, relationships, and —are integrated with existing entities. /// /// - /// Specifies which data to include with each topic. See - /// for details. + /// Specifies which data to include with each topic. See for details. /// /// /// The number of tiers of descendants to load. See for details. /// + /// + /// See for the concurrency contract shared by both overloads. + /// /// A topic object. Task Load( string uniqueKey, @@ -276,8 +286,8 @@ public interface ITopicRepository { /// /// The object to delete. /// - /// Boolean indicator nothing whether to recurse through the 's descendants and delete them as well. If set to false - /// and the topic has children, including any nested topics, an exception will be thrown. The default is false. + /// Boolean indicator nothing whether to recurse through the 's descendants and delete them as well. If + /// set to false and the topic has children, including any nested topics, an exception will be thrown. The default is false. /// /// /// topic is not null From 7777ed1416dd7deabdd09d811685dec2476f54a0 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Wed, 29 Jul 2026 14:15:41 -0700 Subject: [PATCH 288/337] Use lazy-loading in `GetSourceCollectionAsync()` Currently, this forces lazy loading of each collection property it touches, as soon as the `getCollection()` is called, even though it may not actually need the data, thus resulting in multiple calls to the database for each topic. Worse, because these are coming from properties, they're synchronous. We'll be replacing this with a new method that assesses the entire data model for its `TopicPayload` requirements and triggers a single `EnsureLoaded()` call (#118). In preparation for that, I'm kicking things off by fixing this preexisting bug, so that the call to the lazy-loading property is, at least, deferred until it's passed the guard condition (`preconditionsMet`) within the `getCollection()` local function. --- OnTopic/Mapping/TopicMappingService.cs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/OnTopic/Mapping/TopicMappingService.cs b/OnTopic/Mapping/TopicMappingService.cs index a9cab4ce..7adece04 100644 --- a/OnTopic/Mapping/TopicMappingService.cs +++ b/OnTopic/Mapping/TopicMappingService.cs @@ -823,7 +823,7 @@ private async Task> GetSourceCollectionAsync( \-------------------------------------------------------------------------------------------------------------------------*/ listSource = getCollection( CollectionType.Relationship, - source.Relationships.Contains, + key => source.Relationships.Contains(key), () => source.Relationships.GetValues(collectionKey) ); @@ -832,7 +832,7 @@ private async Task> GetSourceCollectionAsync( \-------------------------------------------------------------------------------------------------------------------------*/ listSource = getCollection( CollectionType.NestedTopics, - source.Children.Contains, + key => source.Children.Contains(key), () => source.Children[collectionKey].Children ); @@ -841,7 +841,7 @@ private async Task> GetSourceCollectionAsync( \-------------------------------------------------------------------------------------------------------------------------*/ listSource = getCollection( CollectionType.IncomingRelationship, - source.IncomingRelationships.Contains, + key => source.IncomingRelationships.Contains(key), () => source.IncomingRelationships.GetValues(collectionKey) ); From 6e064a14bf51ec9df4264d5c72dd2941c21c0374 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Wed, 29 Jul 2026 15:33:27 -0700 Subject: [PATCH 289/337] Added unit tests to confirm load order These confirm the previous fix (7777ed14) where the call to `Collection.Contains()` wasn't properly deferred, and thus triggered lazy loading immediately, even if the collection wasn't needed. This confirms that fix works as expected. This includes a new `RelationshipOnlyTopicViewModel` for test purposes. This is part a prior bug fix that was exposed by lazy loading (#111) and will be necessary to resolve as part of the mapping integration (#118). --- OnTopic.Tests/TopicMappingServiceTest.cs | 62 +++++++++++++++++++ .../RelationshipOnlyTopicViewModel.cs | 33 ++++++++++ 2 files changed, 95 insertions(+) create mode 100644 OnTopic.Tests/ViewModels/RelationshipOnlyTopicViewModel.cs diff --git a/OnTopic.Tests/TopicMappingServiceTest.cs b/OnTopic.Tests/TopicMappingServiceTest.cs index 4c761d5a..e24c6dbf 100644 --- a/OnTopic.Tests/TopicMappingServiceTest.cs +++ b/OnTopic.Tests/TopicMappingServiceTest.cs @@ -6,16 +6,20 @@ using System.ComponentModel.DataAnnotations; using System.Globalization; using OnTopic.Data.Caching; +using OnTopic.Lookup; using OnTopic.Mapping; using OnTopic.Mapping.Internal; using OnTopic.Metadata; using OnTopic.Repositories; using OnTopic.TestDoubles; +using OnTopic.TestDoubles.LazyLoading; using OnTopic.TestDoubles.Metadata; using OnTopic.Tests.Entities; using OnTopic.Tests.Fixtures; +using OnTopic.Tests.TestDoubles; using OnTopic.Tests.ViewModels; using OnTopic.Tests.ViewModels.Metadata; +using OnTopic.ViewModels; using Xunit; namespace OnTopic.Tests; @@ -1036,6 +1040,36 @@ public async Task Map_MapAs_ReturnsRelationships() { } + /*============================================================================================================================ + | TEST: MAP: RELATIONSHIP ONLY: DOES NOT FILL CHILDREN + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Maps a , whose only collection is explicitly typed , against a , and confirms that no + /// synchronous fill occurs. Prior to fixing GetSourceCollectionAsync's + /// collection probes, the NestedTopics probe's signature (source.Children.Contains) was evaluated + /// unconditionally when the argument was constructed, silently triggering the lazy loading of the children regardless of + /// which collection type the view model actually requested. + /// + [Fact] + public async Task Map_RelationshipOnly_DoesNotFillChildren() { + + var stub = new StubLazyLoadingTopicRepository(); + var cache = new CachedTopicRepository(stub); + var typeLookupService = new CompositeTypeLookupService(new TopicViewModelLookupService(), new FakeViewModelLookupService()); + var mappingService = new TopicMappingService(cache, typeLookupService); + + var topic = await cache.Load("Root:Web:Web_0"); + + Contract.Assume(topic); + + var target = await mappingService.MapAsync(topic); + + Assert.NotNull(target); + Assert.Equal(0, stub.GetFetchCount(topic.Id, TopicPayload.Children)); + + } + /*============================================================================================================================ | TEST: MAP: TOPIC REFERENCES AS ATTRIBUTE: RETURNS MAPPED MODEL \---------------------------------------------------------------------------------------------------------------------------*/ @@ -1333,6 +1367,34 @@ public async Task Map_FilterByCollectionType_ReturnsFilteredCollection() { } + /*============================================================================================================================ + | TEST: MAP: DESCENDENT: DOES NOT FILL RELATIONSHIPS + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Maps a , whose only collection is , against a + /// , and confirms that no synchronous + /// fill occurs. The inverse of : The relationship probe's method call + /// (source.Relationships.Contains) was likewise evaluated unconditionally. + /// + [Fact] + public async Task Map_Descendent_DoesNotFillRelationships() { + + var stub = new StubLazyLoadingTopicRepository(); + var cache = new CachedTopicRepository(stub); + var typeLookupService = new CompositeTypeLookupService(new TopicViewModelLookupService(), new FakeViewModelLookupService()); + var mappingService = new TopicMappingService(cache, typeLookupService); + + var topic = await cache.Load("Root:Web:Web_0"); + + Contract.Assume(topic); + + var target = await mappingService.MapAsync(topic); + + Assert.NotNull(target); + Assert.Equal(0, stub.GetFetchCount(topic.Id, TopicPayload.Relationships)); + + } + /*============================================================================================================================ | TEST: MAP: GETTER METHODS: MAP METHOD OUTPUT \---------------------------------------------------------------------------------------------------------------------------*/ diff --git a/OnTopic.Tests/ViewModels/RelationshipOnlyTopicViewModel.cs b/OnTopic.Tests/ViewModels/RelationshipOnlyTopicViewModel.cs new file mode 100644 index 00000000..6a8d8682 --- /dev/null +++ b/OnTopic.Tests/ViewModels/RelationshipOnlyTopicViewModel.cs @@ -0,0 +1,33 @@ +/*============================================================================================================================== +| Author Ignia, LLC +| Client Ignia, LLC +| Project Topics Library +\=============================================================================================================================*/ + +namespace OnTopic.Tests.ViewModels; + +/*============================================================================================================================== +| VIEW MODEL: RELATIONSHIP ONLY +\-----------------------------------------------------------------------------------------------------------------------------*/ +/// +/// Provides a simple view model with a single, explicitly typed property (). +/// +/// +/// +/// Intended as a stand-in for cases where a very simple view model is required for test purposes, without introducing other +/// mapping scenarios that might introduce errors, even though they've not part of the test. Unlike , whose maps , is explicitly typed as a relationship, so it exercises only the +/// relationship probe in TopicMappingService.GetSourceCollectionAsync. +/// +/// +/// This is a sample class intended for test purposes only; it is not designed for use in a production environment. +/// +/// +public class RelationshipOnlyTopicViewModel: KeyOnlyTopicViewModel { + + [Collection("Related", Type = CollectionType.Relationship)] + public Collection Related { get; } = new(); + +} //Class \ No newline at end of file From d4b4020261d2245aca5d332ecbe860de84b7c7c5 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Wed, 29 Jul 2026 15:54:35 -0700 Subject: [PATCH 290/337] Ensure `EnsureLoaded()` is awaited Within a synchronous method, we can't call `EnsureLoaded()` with an `await` so we need to use `GetAwaiter().GetResult()`; otherwise, it will run in the background, but the `GetValue()` will (likely) fail assuming it needs get data from the database. This was done correctly in the properties calling `EnsureLoaded()`, but missed in `GetValue()` (9e712ffb). --- OnTopic/Attributes/AttributeCollection.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/OnTopic/Attributes/AttributeCollection.cs b/OnTopic/Attributes/AttributeCollection.cs index e43a30b0..965bd96f 100644 --- a/OnTopic/Attributes/AttributeCollection.cs +++ b/OnTopic/Attributes/AttributeCollection.cs @@ -142,7 +142,7 @@ public bool IsDirty(bool excludeLastModified) bool autoLoad = true ) { if (autoLoad && LoadState is LoadState.NotLoaded && !Contains(key)) { - ((ITopicLazyLoadable)AssociatedTopic).EnsureLoaded(TopicPayload.ExtendedAttributes); + ((ITopicLazyLoadable)AssociatedTopic).EnsureLoaded(TopicPayload.ExtendedAttributes).GetAwaiter().GetResult(); } return base.GetValue(key, defaultValue, inheritFromParent, maxHops, autoLoad); } From 03ed27c762bd21e48f87d7b4233270893c9cddd5 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Thu, 30 Jul 2026 17:32:15 -0700 Subject: [PATCH 291/337] `EnsureLoaded()` for `AsAttributeDictionary()` `AsAttributeDictionary()` is used primarily by the `TopicMappingService` to retrieve all attributes, including derivatives. Unlike a raw enumeration of the collection, it is expected to be an authoritative source of the attributes available and, thus, must ensure that the extended attributes are fully loaded before returning. This patches a gap introduced by the introduction of lazy loading (#111) and contributes to the mapping fixes being implemented as part of #118. In a future update, we'll be identifying what `TopicPayload` the topic needs upfront so the `TopicMappingService` can forecast and do a single `EnsureLoaded()`. Until that lands, this patches an important gap for not only the ``TopicMappingService`, but also any other consumers that rely on this public method. --- OnTopic/Attributes/AttributeCollection.cs | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/OnTopic/Attributes/AttributeCollection.cs b/OnTopic/Attributes/AttributeCollection.cs index 965bd96f..c3d0a9f2 100644 --- a/OnTopic/Attributes/AttributeCollection.cs +++ b/OnTopic/Attributes/AttributeCollection.cs @@ -21,12 +21,12 @@ namespace OnTopic.Attributes; /// The class tracks these through its property, which is an instance of /// the class. /// -/// When is , iterating the collection (e.g., via foreach, -/// LINQ operators, or ) returns only the indexed attributes already present and -/// does not fetch the deferred extended attribute blob. Only a keyed lookup autoloads on a miss. Callers that require a -/// complete set of attributes must first await with . Otherwise, a decision that depends on seeing every attribute may act on a partial -/// view without any error being raised. +/// When is , iterating the collection directly (e.g., via +/// foreach or LINQ operators) returns only the indexed attributes already present and does not fetch the deferred +/// extended attribute blob; only a keyed lookup or autoloads. Callers that +/// enumerate the collection directly and require a complete set of attributes must first await with . Otherwise, a decision that +/// depends on seeing every attribute may act on a partial view without any error being raised. /// /// public class AttributeCollection : TrackedRecordCollection { @@ -217,8 +217,9 @@ public void SetValue( /// /// The method will exclude attributes which correspond to properties on /// which contain specialized getter logic, such as and . Like any enumeration over the collection, this reads only the resident attributes; see the remarks for the completeness contract on a topic. + /// "Topic.LastModified"/>. Unlike a direct enumeration of the collection, this autoloads the extended attribute blob for + /// each source (the current collection, and, if is true, each in the chain) that is , so the result is always complete. /// /// /// Determines if attributes from the should be included. Defaults to false. @@ -229,6 +230,10 @@ public AttributeDictionary AsAttributeDictionary(bool inheritFromBase = false) { var attributes = new AttributeDictionary(); var count = 0; while (sourceAttributes is not null && ++count < 5) { + if (sourceAttributes.LoadState is LoadState.NotLoaded) { + var associatedTopic = (ITopicLazyLoadable)sourceAttributes.AssociatedTopic; + associatedTopic.EnsureLoaded(TopicPayload.ExtendedAttributes).GetAwaiter().GetResult(); + } foreach (var attribute in sourceAttributes) { if (count is 1 || !attributes.ContainsKey(attribute.Key)) { attributes.TryAdd(attribute.Key, attribute.Value); From 51d0f4ede415afd1a03eb48a01e6a303d747b9f7 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Thu, 30 Jul 2026 18:11:12 -0700 Subject: [PATCH 292/337] Added unit test for `AsAttributeDictionary()` fix This validates that the `AsAttributeDictionary()`'s conditional call to `EnsureLoaded()` successfully returns a `LoadState.Loaded` list of attributes, instead of only returning the previously available indexed attributes. This tests a fix (03ed27c7) introduced to patch the `TopicMappingService` (#118) in response to lazy loading (#111). --- OnTopic.Tests/TopicMappingServiceTest.cs | 42 ++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/OnTopic.Tests/TopicMappingServiceTest.cs b/OnTopic.Tests/TopicMappingServiceTest.cs index e24c6dbf..86403e82 100644 --- a/OnTopic.Tests/TopicMappingServiceTest.cs +++ b/OnTopic.Tests/TopicMappingServiceTest.cs @@ -325,6 +325,48 @@ public async Task Map_AttributeDictionary_ReturnsNewModel() { } + /*============================================================================================================================ + | TEST: MAP: ATTRIBUTE DICTIONARY: NOT LOADED: RETURNS EXTENDED ATTRIBUTES + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Establishes a and maps a sparse topic whose extended attributes are still to a view model with an constructor. Confirms the extended + /// attribute is present in the mapped result, i.e., that + /// autoloads the blob rather than silently omitting it by enumerating only resident attributes. + /// + [Fact] + public async Task Map_AttributeDictionary_NotLoaded_ReturnsExtendedAttributes() { + + var records = new StubLazyLoadingTopicRepositoryBuilder() + .AddTopic( + 221, + "Sparse", + "Page", + null, + indexedAttributes : new Dictionary { + ["Title"] = "Value", + ["ShortTitle"] = "Short Title", + ["Subtitle"] = "Subtitle", + ["MetaTitle"] = "Meta Title", + ["MetaDescription"] = "Meta Description" + }, + extendedAttributes : new Dictionary { + ["MappedProperty"] = "Mapped Value" + } + ) + .Build(); + + var stub = new StubLazyLoadingTopicRepository(records); + var topic = await stub.Load("Root:Sparse"); + + Contract.Assume(topic); + + var target = await _mappingService.MapAsync(topic); + + Assert.Equal("Mapped Value", target?.MappedProperty); + + } + /*============================================================================================================================ | TEST: MAP: CONSTRUCTOR: RETURNS NEW MODEL \---------------------------------------------------------------------------------------------------------------------------*/ From faf3639fa8320590c5ebdc8936bd855c9dd2ce78 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Thu, 30 Jul 2026 18:12:24 -0700 Subject: [PATCH 293/337] Ensure view model can't be mapped by reflection The entire purpose of the `AttributeDictionaryConstructorTopicViewModel` is, as the name suggests, to test the `AttributeDictionary` constructor shortcut that bypasses the comparatively expensive reflection-based mapping of well-known view models. To help shore up those tests, I've added `[DisableMapping]` to the view model's properties to ensure that they can _only_ be filled via the constructor. While this isn't necessary for the deliberately unmapped `UnmappedProperty`, as again the name suggested, it helps provide consistency. This is used to ensure that the newly introduced unit test (51d0f4ed) as part of #118 is correctly testing the right mapping method. --- .../AttributeDictionaryConstructorTopicViewModel.cs | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/OnTopic.Tests/ViewModels/AttributeDictionaryConstructorTopicViewModel.cs b/OnTopic.Tests/ViewModels/AttributeDictionaryConstructorTopicViewModel.cs index 942493f2..e6d800f8 100644 --- a/OnTopic.Tests/ViewModels/AttributeDictionaryConstructorTopicViewModel.cs +++ b/OnTopic.Tests/ViewModels/AttributeDictionaryConstructorTopicViewModel.cs @@ -13,7 +13,10 @@ namespace OnTopic.Tests.ViewModels; /// Provides a strongly-typed data transfer object for testing a constructor with a . /// /// -/// This is a sample class intended for test purposes only; it is not designed for use in a production environment. +/// and are decorated with +/// so they can only be populated via the constructor, not the reflection-based property +/// mapper's fallback pass; this isolates tests to the constructor-dictionary path they're meant to exercise. This is a sample +/// class intended for test purposes only; it is not designed for use in a production environment. /// public record AttributeDictionaryConstructorTopicViewModel: PageTopicViewModel { @@ -38,7 +41,10 @@ public AttributeDictionaryConstructorTopicViewModel() { } /*============================================================================================================================ | PROPERTIES \---------------------------------------------------------------------------------------------------------------------------*/ + [DisableMapping] public string? MappedProperty { get; init; } + + [DisableMapping] public string? UnmappedProperty { get; init; } From b88d436f48b3a40269609e92ef6328c85ca39be9 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Thu, 30 Jul 2026 18:12:43 -0700 Subject: [PATCH 294/337] Ensure metadata lookup items are loaded on mapping A metadata relationships allows a reference to a lookup list, typically (but not necessarily) in the configuration for e.g., a list of countries or states or lookup information. It is typically bound to the interface of a view model for the purpose of forms. Given this, when the `TopicMappingService` processes the `MetadataKey`, it needs to ensure that the key's `TopicPayload.Children` are properly loaded so they're available to be bound. This patches another gap in the `TopicMappingService` (#118) in response to the lazy-loading implementation (#111). --- OnTopic/Mapping/TopicMappingService.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/OnTopic/Mapping/TopicMappingService.cs b/OnTopic/Mapping/TopicMappingService.cs index 7adece04..4c335a5a 100644 --- a/OnTopic/Mapping/TopicMappingService.cs +++ b/OnTopic/Mapping/TopicMappingService.cs @@ -872,7 +872,7 @@ sourcePropertyValue[0] is Topic \-------------------------------------------------------------------------------------------------------------------------*/ if (listSource.Count == 0 && !String.IsNullOrWhiteSpace(configuration.MetadataKey)) { var metadataKey = $"Root:Configuration:Metadata:{configuration.MetadataKey}:LookupList"; - var metadataParent = await _topicRepository.Load(metadataKey, source).ConfigureAwait(false); + var metadataParent = await _topicRepository.Load(metadataKey, source, TopicPayload.Children).ConfigureAwait(false); if (metadataParent is not null) { listSource = [.. metadataParent.Children]; } From f287c1d181b7066773116dc493e50950fe21ae41 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Thu, 30 Jul 2026 19:00:36 -0700 Subject: [PATCH 295/337] Prevent duplicate mapping of properties This fixes a preexisting bug where, if the same view model ends up being mapped twice with different requirements, the scalar properties were remapped. This doesn't trigger a reload since any extended attributes would have been loaded the first time around, but it does waste CPU cycles by remapping existing properties that aren't relevant to this round. This happens because for collections and references, attributes can limit which collection properties, if any, get mapped, to allow view models to be reused while limiting their potential to keep triggering mapping of associations that aren't needed. So if one reference or collection disables the mapping of associations, but then a subsequent reference or collection maps the _same_ view model on the _same_ topic, but includes an `[Include]` attribute including associations, we don't need to remap the properties that were already mapped in the first round. This is mitigated by adding a `mapAssociationsOnly` argument to `SetCollectionValueAsync()` and `GetSourceCollectionAsync()` and setting them appropriately on these redundant checks. This bug existed before the lazy-loading (#111) and doesn't contribute to any concurrency issues due to the collections being marked `LoadState.Loaded` after the initial call, and thus this isn't strictly required by #118, but it's good to fix while we're here! --- OnTopic/Mapping/TopicMappingService.cs | 27 ++++++++++++++++---------- 1 file changed, 17 insertions(+), 10 deletions(-) diff --git a/OnTopic/Mapping/TopicMappingService.cs b/OnTopic/Mapping/TopicMappingService.cs index 4c335a5a..d6358833 100644 --- a/OnTopic/Mapping/TopicMappingService.cs +++ b/OnTopic/Mapping/TopicMappingService.cs @@ -423,7 +423,7 @@ private async Task MapAsync( \-------------------------------------------------------------------------------------------------------------------------*/ async Task getList(Type targetType) { - var sourceList = await GetSourceCollectionAsync(source, associations, parameter, attributePrefix).ConfigureAwait(false); + var sourceList = await GetSourceCollectionAsync(source, associations, parameter, attributePrefix, false).ConfigureAwait(false); var targetList = InitializeCollection(targetType); if (targetList is null) { @@ -496,7 +496,7 @@ await MapAsync( else { var value = await GetValue(source, propertyAccessor.Type, associations, propertyAccessor, cache, attributePrefix, mapAssociationsOnly).ConfigureAwait(false); if (value is null && propertyAccessor.IsList) { - await SetCollectionValueAsync(source, target, associations, propertyAccessor, cache, attributePrefix).ConfigureAwait(false); + await SetCollectionValueAsync(source, target, associations, propertyAccessor, cache, attributePrefix, mapAssociationsOnly).ConfigureAwait(false); } else if (value != null && propertyAccessor.CanWrite) { propertyAccessor.SetValue(target, value, true); @@ -549,7 +549,7 @@ await MapAsync( /*-------------------------------------------------------------------------------------------------------------------------- | Handle by type, attribute \-------------------------------------------------------------------------------------------------------------------------*/ - if (TryGetCompatibleProperty(source, targetType, itemMetadata, attributePrefix, out var compatibleValue)) { + if (!mapAssociationsOnly && TryGetCompatibleProperty(source, targetType, itemMetadata, attributePrefix, out var compatibleValue)) { value = compatibleValue; } else if (itemMetadata.IsConvertible) { @@ -729,13 +729,15 @@ await MapAsync( /// The with details about the property's attributes. /// A cache to keep track of already-mapped object instances. /// The prefix to apply to the attributes. + /// Determines if properties not associated with associations should be mapped. private async Task SetCollectionValueAsync( Topic source, object target, AssociationTypes associations, MemberAccessor memberAccessor, MappedTopicCache cache, - string? attributePrefix + string? attributePrefix, + bool mapAssociationsOnly ) { /*-------------------------------------------------------------------------------------------------------------------------- @@ -756,7 +758,7 @@ private async Task SetCollectionValueAsync( /*-------------------------------------------------------------------------------------------------------------------------- | Establish source collection to store topics to be mapped \-------------------------------------------------------------------------------------------------------------------------*/ - var sourceList = await GetSourceCollectionAsync(source, associations, memberAccessor, attributePrefix).ConfigureAwait(false); + var sourceList = await GetSourceCollectionAsync(source, associations, memberAccessor, attributePrefix, mapAssociationsOnly).ConfigureAwait(false); /*-------------------------------------------------------------------------------------------------------------------------- | Validate that source collection was identified @@ -788,11 +790,13 @@ private async Task SetCollectionValueAsync( /// Determines what associations the mapping should include, if any. /// The with details about the property's attributes. /// The prefix to apply to the attributes. + /// Determines if properties not associated with associations should be mapped. private async Task> GetSourceCollectionAsync( Topic source, AssociationTypes associations, ItemMetadata itemMetadata, - string? attributePrefix + string? attributePrefix, + bool mapAssociationsOnly ) { /*-------------------------------------------------------------------------------------------------------------------------- @@ -850,9 +854,11 @@ private async Task> GetSourceCollectionAsync( \-------------------------------------------------------------------------------------------------------------------------*/ //The following allows a target collection to be mapped to an IList source collection. This is valuable for custom, //curated collections defined on e.g. derivatives of Topic, but which don't otherwise map to a specific collection type. - //For example, the ContentTypeDescriptor's AttributeDescriptors collection, which provides a rollup of - //AttributeDescriptors from the current ContentTypeDescriptor, as well as all of its ascendents. - if (listSource.Count == 0) { + //For example, the ContentTypeDescriptor's AttributeDescriptors collection, which provides a rollup of AttributeDescriptors + //from the current ContentTypeDescriptor, as well as all of its ascendants. On an expansion pass, this fallback runs only + //when MappedCollections is among the claimed associations, avoiding a redundant reflective source-property read (and its + //re-enumeration) for passes that don't claim it. + if (listSource.Count == 0 && (!mapAssociationsOnly || associations.HasFlag(AssociationTypes.MappedCollections))) { var sourceProperty = TypeAccessorCache.GetTypeAccessor(source.GetType()).GetMember(configuration.GetCompositeAttributeKey(attributePrefix)); if ( sourceProperty?.GetValue(source) is IList sourcePropertyValue && @@ -870,7 +876,7 @@ sourcePropertyValue[0] is Topic /*-------------------------------------------------------------------------------------------------------------------------- | Handle Metadata relationship \-------------------------------------------------------------------------------------------------------------------------*/ - if (listSource.Count == 0 && !String.IsNullOrWhiteSpace(configuration.MetadataKey)) { + if (!mapAssociationsOnly && listSource.Count == 0 && !String.IsNullOrWhiteSpace(configuration.MetadataKey)) { var metadataKey = $"Root:Configuration:Metadata:{configuration.MetadataKey}:LookupList"; var metadataParent = await _topicRepository.Load(metadataKey, source, TopicPayload.Children).ConfigureAwait(false); if (metadataParent is not null) { @@ -896,6 +902,7 @@ IList getCollection(CollectionType collection, Func contain var targetAssociations = AssociationMap.Mappings[collection]; var preconditionsMet = listSource.Count == 0 && + (!mapAssociationsOnly || targetAssociations is not AssociationTypes.None) && (collectionType is CollectionType.Any || collectionType.Equals(collection)) && (collectionType is CollectionType.Children || collection is not CollectionType.Children) && (targetAssociations is AssociationTypes.None || associations.HasFlag(targetAssociations)) && From ec102ab208d399ab800f90cd377b9414ea6d2f5a Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sat, 1 Aug 2026 15:45:25 -0700 Subject: [PATCH 296/337] Introduced view models to test expanded maps These two test view models help evaluate the scenario where an already mapped view model in an association is remapped with additional `[include()]` calls, a scenario which previously resulted in the "compatible" properties" being mapped twice, and as fixed in the previous commit (f287c1d1). This will be used in a subsequent unit test to verify the fix. This bug existed before the lazy-loading (#111) and doesn't contribute to any concurrency issues due to the collections being marked `LoadState.Loaded` after the initial call, and thus this isn't strictly required by #118. --- .../TestDoubles/FakeViewModelLookupService.cs | 2 + .../ExpansionParentTopicViewModel.cs | 57 +++++++++++++++ .../ExpansionSharedTopicViewModel.cs | 73 +++++++++++++++++++ 3 files changed, 132 insertions(+) create mode 100644 OnTopic.Tests/ViewModels/ExpansionParentTopicViewModel.cs create mode 100644 OnTopic.Tests/ViewModels/ExpansionSharedTopicViewModel.cs diff --git a/OnTopic.Tests/TestDoubles/FakeViewModelLookupService.cs b/OnTopic.Tests/TestDoubles/FakeViewModelLookupService.cs index fc379c2d..1f24a195 100644 --- a/OnTopic.Tests/TestDoubles/FakeViewModelLookupService.cs +++ b/OnTopic.Tests/TestDoubles/FakeViewModelLookupService.cs @@ -41,6 +41,8 @@ public FakeViewModelLookupService() { Add(typeof(DescendentSpecializedTopicViewModel)); Add(typeof(DescendentTopicViewModel)); Add(typeof(DisableMappingTopicViewModel)); + Add(typeof(ExpansionParentTopicViewModel)); + Add(typeof(ExpansionSharedTopicViewModel)); Add(typeof(FallbackViewModel)); Add(typeof(FilteredTopicViewModel)); Add(typeof(FlattenChildrenTopicViewModel)); diff --git a/OnTopic.Tests/ViewModels/ExpansionParentTopicViewModel.cs b/OnTopic.Tests/ViewModels/ExpansionParentTopicViewModel.cs new file mode 100644 index 00000000..49f15956 --- /dev/null +++ b/OnTopic.Tests/ViewModels/ExpansionParentTopicViewModel.cs @@ -0,0 +1,57 @@ +/*============================================================================================================================== +| Author Ignia, LLC +| Client Ignia, LLC +| Project Topics Library +\=============================================================================================================================*/ + +namespace OnTopic.Tests.ViewModels; + +/*============================================================================================================================== +| VIEW MODEL: EXPANSION PARENT +\-----------------------------------------------------------------------------------------------------------------------------*/ +/// +/// Provides a view model whose two collections both map the same source topic to , +/// but request disjoint associations so that mapping it can exercise an association expansion pass. +/// +/// +/// +/// The relationship and the collection are populated from the same source +/// topic and mapped to the same instance, but request disjoint associations +/// ( and ). Neither association maps +/// anything on , which has no association-typed members: The disjoint requests +/// exist only so the cache sees the second encounter as missing an association and runs an expansion pass, rather than +/// returning the cached instance unchanged. What that expansion pass must not do is redo the target's non-association work. +/// +/// +/// The disjointness is all this view model contributes, and only conditionally: If one encounter finds the instance the +/// other already cached, that encounter has a missing association. Whether the encounters actually resolve that way, as an +/// ordered initial pass followed by a cache-hit expansion pass rather than two concurrent initial passes, is a property +/// of the mapping runtime, not of this view model. The tests that depend on the ordered outcome document why it holds for +/// them. +/// +/// +/// This is a sample class intended for test purposes only; it is not designed for use in a production environment. +/// +/// +public class ExpansionParentTopicViewModel { + + /*============================================================================================================================ + | PROPERTY: RELATED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// A relationship collection that reaches the shared topic while requesting only . + /// + [Collection("Related", Type = CollectionType.Relationship)] + [Include(AssociationTypes.Children)] + public Collection Related { get; } = new(); + + /*============================================================================================================================ + | PROPERTY: CHILDREN + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// A children collection that reaches the shared topic while requesting only . + /// + [Include(AssociationTypes.Relationships)] + public Collection Children { get; } = new(); + +} //Class \ No newline at end of file diff --git a/OnTopic.Tests/ViewModels/ExpansionSharedTopicViewModel.cs b/OnTopic.Tests/ViewModels/ExpansionSharedTopicViewModel.cs new file mode 100644 index 00000000..3c3efbcb --- /dev/null +++ b/OnTopic.Tests/ViewModels/ExpansionSharedTopicViewModel.cs @@ -0,0 +1,73 @@ +/*============================================================================================================================== +| Author Ignia, LLC +| Client Ignia, LLC +| Project Topics Library +\=============================================================================================================================*/ + +namespace OnTopic.Tests.ViewModels; + +/*============================================================================================================================== +| VIEW MODEL: EXPANSION SHARED +\-----------------------------------------------------------------------------------------------------------------------------*/ +/// +/// Provides a view model that encounters more than once during a single mapping +/// operation, so that the second encounter triggers an association expansion pass (mapAssociationsOnly), while the +/// first only includes the properties. +/// +/// +/// +/// This has no association-typed members by design. Its content is , an ungated (gate ) nested-topics collection, and , a "compatible" property (i.e., mapped +/// directly from a first-class property on ). Unlike a gated association, which the cache claims once +/// and its flag check then skips on later passes, neither of these is tied to an association, so an expansion pass would +/// redundantly remap both unless the mapper explicitly skips non-association work. records how +/// many times is assigned, so a test can confirm the compatible property is not reassigned again during +/// the expansion pass. +/// +/// +/// This is only reachable in tandem with , whose two collections perform the +/// initial and expansion passes against a single, cached instance of this view model. +/// +/// +/// This is a sample class intended for test purposes only; it is not designed for use in a production environment. +/// +/// +public class ExpansionSharedTopicViewModel { + + /*============================================================================================================================ + | PRIVATE VARIABLES + \---------------------------------------------------------------------------------------------------------------------------*/ + private int _keyMapCount; + + /*============================================================================================================================ + | PROPERTY: KEY + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// A compatible property, mapped one-to-one from the source . Records each assignment via . + /// + public string? Key { + get; + set { + field = value; + _keyMapCount++; + } + } + + /*============================================================================================================================ + | PROPERTY: KEY MAP COUNT + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// The number of times has been assigned by the mapping service. + /// + public int KeyMapCount => _keyMapCount; + + /*============================================================================================================================ + | PROPERTY: CATEGORIES + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// An ungated nested-topics collection, mapped from the source topic's nested Categories container. + /// + public Collection Categories { get; } = new(); + +} //Class \ No newline at end of file From 49a604890b127b18eb6e2795400e071bd1d1f045 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sat, 1 Aug 2026 16:01:22 -0700 Subject: [PATCH 297/337] Added unit tests to confirm properties mapped once This test evaluates the scenario where an already mapped view model in an association is remapped with additional `[include()]` calls, a scenario which previously resulted in the "compatible" properties" being mapped twice, and as fixed in the previous commit (f287c1d1). This relies on the two newly introduced view models (ec102ab2) to ensure the circumstances are met. This bug existed before the lazy-loading (#111) and doesn't contribute to any concurrency issues due to the collections being marked `LoadState.Loaded` after the initial call, and thus this isn't strictly required by #118. --- OnTopic.Tests/TopicMappingServiceTest.cs | 72 ++++++++++++++++++++++++ 1 file changed, 72 insertions(+) diff --git a/OnTopic.Tests/TopicMappingServiceTest.cs b/OnTopic.Tests/TopicMappingServiceTest.cs index 86403e82..3b0874ec 100644 --- a/OnTopic.Tests/TopicMappingServiceTest.cs +++ b/OnTopic.Tests/TopicMappingServiceTest.cs @@ -1363,6 +1363,78 @@ public async Task Map_CachedTopic_ReturnsProgressiveReference() { } + /*============================================================================================================================ + | TEST: MAP: EXPANSION PASS: DOES NOT DUPLICATE NESTED TOPICS + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Maps an , which encounters the same source topic twice with disjoint + /// associations, confirming that the second (expansion) pass does not re-append the ungated nested-topics collection that + /// the initial pass already populated. + /// + /// + /// Reliability rests on the eager repository mapping the two collections sequentially, so the encounters are strictly + /// ordered: The first builds and fills the cached view model, and the second, requesting a disjoint association, hits the + /// cache and runs an expansion pass (rather than a second, concurrent initial pass). is then filled once by the ungated nested-topics probe on the initial pass + /// and skipped on the expansion pass, so the count is 2 whichever collection reflection maps first. + /// + [Fact] + public async Task Map_ExpansionPass_DoesNotDuplicateNestedTopics() { + + var parent = new Topic("Parent", "ExpansionParent", null, 700); + var shared = new Topic("Shared", "ExpansionShared", parent, 701); + var categories = new Topic("Categories", "List", shared, 702); + _ = new Topic("Category1", "KeyOnly", categories, 703); + _ = new Topic("Category2", "KeyOnly", categories, 704); + + parent.Relationships.SetValue("Related", shared); + + var target = await _mappingService.MapAsync(parent); + var mappedShared = target?.Children.FirstOrDefault(); + + //Assert.Same confirms both collections resolved to the same cached instance, so the second reach was a cache hit and, given + //the disjoint associations, ran an expansion pass + Assert.NotNull(mappedShared); + Assert.Same(mappedShared, target?.Related.FirstOrDefault()); + Assert.Equal(2, mappedShared.Categories.Count); + + } + + /*============================================================================================================================ + | TEST: MAP: EXPANSION PASS: DOES NOT REMAP COMPATIBLE PROPERTY + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Maps an , which encounters the same source topic twice with disjoint + /// associations, and confirms that the second (expansion) pass does not reassign the compatible property that the initial pass already mapped. + /// + /// + /// Reliability rests on the eager repository mapping the two collections sequentially, so the encounters are strictly + /// ordered: The first builds and fills the cached view model, and the second, requesting a disjoint association, hits the + /// cache and runs an expansion pass (rather than a second, concurrent initial pass). The compatible is then assigned once on the initial pass and skipped on the expansion pass, so + /// is 1 whichever collection reflection maps first. + /// + [Fact] + public async Task Map_ExpansionPass_DoesNotRemapCompatibleProperty() { + + var parent = new Topic("Parent", "ExpansionParent", null, 710); + var shared = new Topic("Shared", "ExpansionShared", parent, 711); + + parent.Relationships.SetValue("Related", shared); + + var target = await _mappingService.MapAsync(parent); + var mappedShared = target?.Children.FirstOrDefault(); + + //Assert.Same confirms both collections resolved to the same cached instance, so the second reach was a cache hit and, given + //the disjoint associations, ran an expansion pass rather than passing vacuously + Assert.NotNull(mappedShared); + Assert.Same(mappedShared, target?.Related.FirstOrDefault()); + Assert.Equal("Shared", mappedShared.Key); + Assert.Equal(1, mappedShared.KeyMapCount); + + } + /*============================================================================================================================ | TEST: MAP: CIRCULAR REFERENCE: RETURNS MAPPED PARENT \---------------------------------------------------------------------------------------------------------------------------*/ From 0f512648e25c4308f1a4a62c05e868d6204c4102 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sat, 1 Aug 2026 17:40:22 -0700 Subject: [PATCH 298/337] Made `AddMissingAssociations()` concurrent Added a lock to the `AddMissingAssociations()` and, importantly, now return what the newly added associations are, so that the caller only need to process those that are new. This ensures that if there are two overlapping calls, they won't end up processing the same associations. This bug existed before the lazy-loading (#111), but addresses a concurrency issue already exposed by the `TopicMappingService` (#118). --- .../Mapping/Internal/MappedTopicCacheEntry.cs | 40 +++++++++++++++---- 1 file changed, 32 insertions(+), 8 deletions(-) diff --git a/OnTopic/Mapping/Internal/MappedTopicCacheEntry.cs b/OnTopic/Mapping/Internal/MappedTopicCacheEntry.cs index e37fb3b6..794dcdea 100644 --- a/OnTopic/Mapping/Internal/MappedTopicCacheEntry.cs +++ b/OnTopic/Mapping/Internal/MappedTopicCacheEntry.cs @@ -15,14 +15,20 @@ namespace OnTopic.Mapping.Internal; /// /// /// In addition to the actual , this also includes a property for -/// tracking what associations were mapped to the . This allows the to be update the cached object with any missing associations, which can be identified using the method. In turn, the cache can then be updated to reflect those new -/// associations by using . This ensures that even if a topic has -/// already been mapped, its scope can be expanded without duplicating effort. +/// tracking what associations were mapped to the . This allows the +/// to expand the cached object with any missing associations. A caller may peek at the missing associations using the +/// method, or record them and receive the newly added subset in a +/// single atomic operation using , so that concurrent passes don't both +/// end up mapping the same associations. This ensures that even if a topic has already been mapped, its scope can be expanded +/// without duplicating effort. /// internal sealed class MappedTopicCacheEntry { + /*============================================================================================================================ + | PRIVATE VARIABLES + \---------------------------------------------------------------------------------------------------------------------------*/ + private readonly object _lock = new(); + /*============================================================================================================================ | PROPERTY: MAPPED TOPIC \---------------------------------------------------------------------------------------------------------------------------*/ @@ -61,15 +67,33 @@ internal sealed class MappedTopicCacheEntry { /// Given a target , identifies any associations not covered by /// and returns them as a new instance. /// + /// + /// This is intended as a quick hint to decide e.g., whether an expansion is needed at all, without any side effects. It + /// does not record the result; a caller that intends to map the missing associations should instead use , so that concurrent passes cannot both map the same associations. + /// internal AssociationTypes GetMissingAssociations(AssociationTypes associations) => Associations ^ (associations | Associations); /*============================================================================================================================ | METHOD: ADD MISSING ASSOCIATIONS \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Given a target , adds any missing to the property. + /// Given a target , adds any not already covered by and returns + /// the subset that this call just added. /// - internal void AddMissingAssociations(AssociationTypes associations) => Associations = associations | Associations; + /// + /// This is the mutating counterpart to : It adds any associations + /// that aren't already covered, and reports which ones were added back to the caller so the caller knows which associations + /// to process. Because the delta is calculated and saved under a single lock, two concurrent passes over the same cached + /// instance receive disjoint results, ensuring each association is mapped by exactly one caller. A caller that receives + /// has nothing left to map and should return the cached instance. + /// + internal AssociationTypes AddMissingAssociations(AssociationTypes associations) { + lock (_lock) { + var missing = GetMissingAssociations(associations); + Associations = associations | Associations; + return missing; + } + } } //Class \ No newline at end of file From a971aeb84e7da4835468e9d702c3d29c2ac133ca Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sat, 1 Aug 2026 17:45:11 -0700 Subject: [PATCH 299/337] Applied `AddMissingAssociations()` to caller This utilizes the new return value from the updated `AddMissingAssociations()` method on the `MappedTopicCacheEntry` to ensure that it's only mapping still missing associations, acknowledging that a concurrent call may have already began mapping some that it has previously identified. This bug existed before the lazy-loading (#111), but addresses a concurrency issue already exposed by the `TopicMappingService` (#118). --- OnTopic/Mapping/TopicMappingService.cs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/OnTopic/Mapping/TopicMappingService.cs b/OnTopic/Mapping/TopicMappingService.cs index d6358833..9d64eba5 100644 --- a/OnTopic/Mapping/TopicMappingService.cs +++ b/OnTopic/Mapping/TopicMappingService.cs @@ -326,15 +326,15 @@ private async Task MapAsync( | Handle cached objects >------------------------------------------------------------------------------------------------------------------------- | If the cache contains an entry, check to make sure it includes all of the requested associations. If it does, return it. - | If it doesn't, determine the missing associations and request to have those mapped. + | Otherwise, add the missing associations to the cache entry and map only the subset this pass added, so that a concurrent + | pass doesn't remap the same associations. \-------------------------------------------------------------------------------------------------------------------------*/ if (cache.TryGetValue(topic.Id, target.GetType(), out var cacheEntry)) { - associations = cacheEntry.GetMissingAssociations(associations); + associations = cacheEntry.AddMissingAssociations(associations); target = cacheEntry.MappedTopic; if (associations is AssociationTypes.None) { return cacheEntry.MappedTopic; } - cacheEntry.AddMissingAssociations(associations); } else if (!topic.IsNew) { cache.Register( From bc73f876ebc600cb65298435afcf70c176dea09f Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Sat, 1 Aug 2026 17:48:03 -0700 Subject: [PATCH 300/337] Update unit tests for `AddMissingAssociations()` This updates the existing unit tests for `AddMissingAssociations()` to account for the concurrency fix (0f512648, a971aeb8) related to #118. --- OnTopic.Tests/TopicMappingServiceTest.cs | 26 +++++++++++++++--------- 1 file changed, 16 insertions(+), 10 deletions(-) diff --git a/OnTopic.Tests/TopicMappingServiceTest.cs b/OnTopic.Tests/TopicMappingServiceTest.cs index 3b0874ec..8a8fd20f 100644 --- a/OnTopic.Tests/TopicMappingServiceTest.cs +++ b/OnTopic.Tests/TopicMappingServiceTest.cs @@ -761,8 +761,6 @@ public void MappedTopicCacheEntry_GetMissingAssociations_ReturnsDifference() { var difference = cacheEntry.GetMissingAssociations(associations); - cacheEntry.AddMissingAssociations(difference); - Assert.True(difference.HasFlag(AssociationTypes.References)); Assert.False(difference.HasFlag(AssociationTypes.Children)); Assert.False(difference.HasFlag(AssociationTypes.Parents)); @@ -770,24 +768,32 @@ public void MappedTopicCacheEntry_GetMissingAssociations_ReturnsDifference() { } /*============================================================================================================================ - | TEST: MAPPED TOPIC CACHE ENTRY: ADD MISSING ASSOCIATIONS: SETS UNION + | TEST: MAPPED TOPIC CACHE ENTRY: ADD MISSING ASSOCIATIONS: RETURNS NEWLY ADDED \---------------------------------------------------------------------------------------------------------------------------*/ /// - /// Establishes a with a set of , and then confirms that - /// its correctly extends the missing - /// associations. + /// Establishes a and then confirms that two overlapping calls to its return disjoint flags (each reporting only what it + /// newly added) whose union is the missing set, and that the recorded + /// reflect both calls. /// + /// + /// Each association may only be added once. Even though both requests include , + /// only the first call adds it; the second call sees it as already recorded and returns only the remainder. This is what + /// ensures two concurrent passes map disjoint associations rather than both mapping the overlap. + /// [Fact] - public void MappedTopicCacheEntry_AddMissingAssociations_SetsUnion() { + public void MappedTopicCacheEntry_AddMissingAssociations_ReturnsNewlyAdded() { var cacheEntry = new MappedTopicCacheEntry() { Associations = AssociationTypes.Children }; - var associations = AssociationTypes.Children | AssociationTypes.Parents; - cacheEntry.AddMissingAssociations(associations); + var firstResult = cacheEntry.AddMissingAssociations(AssociationTypes.Children | AssociationTypes.Parents); + var secondResult = cacheEntry.AddMissingAssociations(AssociationTypes.Parents | AssociationTypes.References); - Assert.Equal(AssociationTypes.Children | AssociationTypes.Parents, cacheEntry.Associations); + Assert.Equal(AssociationTypes.Parents, firstResult); + Assert.Equal(AssociationTypes.References, secondResult); + Assert.Equal(AssociationTypes.Children | AssociationTypes.Parents | AssociationTypes.References, cacheEntry.Associations); } From b42673a4f1e0d391475f056ad6b48a3e2660cfee Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Mon, 3 Aug 2026 16:19:03 -0700 Subject: [PATCH 301/337] Introduce new `MapPath` class The `MapPath` class will track the chain of a `MapAsync()` process (via the `Parent` property) to determine what topic (via the `TopicId` property) and mapped view model type (via the `Type` property) are in the process of being mapped as part of this specific request, this allowing us to determine if there's a circular reference. This allows constructor mapping (aside from `AttributeDictionary`; #99) to properly map e.g., positional constructors on records, a current capability (#35). This allows us to differentiate between true circular loops within a constructor (which can't be supported) and sibling mappings (which are valid), with the latter now introducing potential concurrency issues (#118) because lazy loading (#111) makes construction suspend on an awaited `Load()`, where this previously completed synchronously, running each branch to completion before the next. This will allow multiple branches to construct the same topic and view model at once, an acceptable overlap `MapPath()` will now be able to distinguish from a circular loop. --- OnTopic/Mapping/Internal/MapPath.cs | 71 +++++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) create mode 100644 OnTopic/Mapping/Internal/MapPath.cs diff --git a/OnTopic/Mapping/Internal/MapPath.cs b/OnTopic/Mapping/Internal/MapPath.cs new file mode 100644 index 00000000..1403fabd --- /dev/null +++ b/OnTopic/Mapping/Internal/MapPath.cs @@ -0,0 +1,71 @@ +/*============================================================================================================================== +| Author Ignia, LLC +| Client Ignia, LLC +| Project Topics Library +\=============================================================================================================================*/ + +namespace OnTopic.Mapping.Internal; + +/*============================================================================================================================== +| CLASS: MAP PATH +\-----------------------------------------------------------------------------------------------------------------------------*/ +/// +/// Represents a single frame in the depth-first path of an in-progress mapping operation, tracking the +/// and target currently being constructed, along with a reference to the frame that preceded it. +/// +/// +/// The allows the to distinguish a genuine constructor cycle, in +/// which a topic is mapped to a type that is already being constructed higher up the same call chain, from sibling +/// concurrency, in which two independent branches happen to map the same topic to the same type at the same time. The former +/// is a true circular reference and must throw; the latter is benign, and the joiner should await the in-progress result. +/// +/// The of the topic being mapped at this frame. +/// The target being constructed at this frame. +/// The preceding frame, or null if this frame is the path root. +internal sealed class MapPath(int topicId, Type type, MapPath? parent) { + + /*============================================================================================================================ + | PROPERTY: TOPIC ID + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// The of the topic being mapped at this frame. + /// + internal int TopicId { get; } = topicId; + + /*============================================================================================================================ + | PROPERTY: TYPE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// The target being constructed at this frame. + /// + internal Type Type { get; } = type; + + /*============================================================================================================================ + | PROPERTY: PARENT + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// The preceding frame, or null if this frame is the root of the path. + /// + internal MapPath? Parent { get; } = parent; + + /*============================================================================================================================ + | METHOD: CONTAINS + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Determines whether the supplied and pair already appears anywhere on + /// the current path, indicating a constructor cycle. + /// + /// The to search for. + /// The target to search for. + /// Returns true if the pair is already on the path, and otherwise false. + internal bool Contains(int topicId, Type type) { + // Walk up the parent chain, comparing each frame against the requested pair + for (var frame = this; frame is not null; frame = frame.Parent) { + if (frame.TopicId == topicId && frame.Type == type) { + return true; + } + } + return false; + } + +} //Class \ No newline at end of file From 7a5bd2c2afd3a96e8ad89624f78cca0c2702196e Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Mon, 3 Aug 2026 18:06:49 -0700 Subject: [PATCH 302/337] Added completion semantics to mapped cache entries Added the `Completion` property (similar to e.g., `IDataflowBlock` and `ChannelReader` in the BCL) to `MappedTopicCacheEntry` so that a concurrent request can `await` the construction of the initial entry instead of duplicating effort and, potentially, causing an error. This includes a `Complete()` method as well as a `Fault()` method. This will be used to ensure that one topic can be concurrently mapped to the same view model without interference (#118). --- .../Mapping/Internal/MappedTopicCacheEntry.cs | 55 +++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/OnTopic/Mapping/Internal/MappedTopicCacheEntry.cs b/OnTopic/Mapping/Internal/MappedTopicCacheEntry.cs index 794dcdea..b5fae15e 100644 --- a/OnTopic/Mapping/Internal/MappedTopicCacheEntry.cs +++ b/OnTopic/Mapping/Internal/MappedTopicCacheEntry.cs @@ -28,6 +28,7 @@ internal sealed class MappedTopicCacheEntry { | PRIVATE VARIABLES \---------------------------------------------------------------------------------------------------------------------------*/ private readonly object _lock = new(); + private readonly TaskCompletionSource _completionSource = new(TaskCreationOptions.RunContinuationsAsynchronously); /*============================================================================================================================ | PROPERTY: MAPPED TOPIC @@ -60,6 +61,24 @@ internal sealed class MappedTopicCacheEntry { /// internal AssociationTypes Associations { get; set; } = AssociationTypes.None; + /*============================================================================================================================ + | PROPERTY: COMPLETION + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Returns a that completes once the has been constructed and registered, even + /// if not all properties have yet been mapped, thus allowing a second pass to await a first pass that is still initializing + /// the same entry, instead of duplicating its work or, worse yet, failing. + /// + /// + /// The task is settled by once the target has been constructed, or by + /// if construction throws, so a second pass awaiting it never hangs. It is settled during + /// registration, after the constructor runs but before the first pass maps the target's properties, so a second pass may + /// observe an instance whose constructor parameters are set but whose properties are not yet mapped. This early publication + /// is what allows a property-level circular reference to resolve to the cached (if partially populated) instance instead of + /// recursing indefinitely, while still catching constructor-level circular references. + /// + internal Task Completion => _completionSource.Task; + /*============================================================================================================================ | METHOD: GET MISSING ASSOCIATIONS \---------------------------------------------------------------------------------------------------------------------------*/ @@ -96,4 +115,40 @@ internal AssociationTypes AddMissingAssociations(AssociationTypes associations) } } + /*============================================================================================================================ + | METHOD: COMPLETE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Publishes the constructed and its as the entry's and , and settles the task, releasing any second pass + /// awaiting this entry. + /// + /// + /// This is the sole writer of and the initial writer of , so the + /// instance, its associations, and the completion signal are always published together under a single lock. Only the first + /// completion takes effect; a later duplicate registration is ignored, keeping the cached instance stable, while remaining + /// unobservable before the entry is completed. + /// + /// The constructed view model associated with the entry. + /// The associations that the view model was mapped with. + internal void Complete(object viewModel, AssociationTypes associations) { + lock (_lock) { + if (!_completionSource.Task.IsCompleted) { + MappedTopic = viewModel; + Associations = associations; + _completionSource.TrySetResult(); + } + } + } + + /*============================================================================================================================ + | METHOD: FAULT + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Faults the task with the supplied so that any pass awaiting the + /// entry observes the failure instead of hanging when construction of the entry throws. + /// + /// The exception that occurred while constructing the entry. + internal void Fault(Exception exception) => _completionSource.TrySetException(exception); + } //Class \ No newline at end of file From 61b1487c78aeee203d9f360851ea8e9b342fd6ef Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Mon, 3 Aug 2026 19:00:30 -0700 Subject: [PATCH 303/337] Added `MapPath` to `MapAsync()` chain This adds the new `MapPath` data object (b42673a4) to the private `MapAsync()` overloads as well as their entire call chain (i.e., `GetParameterAsync()`, `GetTopicReferenceAsync()`, `GetValue()`, `SetPropertyAsync()`, `SetCollectionValueAsync()`, `PopulateTargetCollectionAsync()`). Currently, this doesn't _do_ anything, though once implemented, this will allow us to differentiate between true circular loops within a constructor (which can't be supported) and sibling mappings (which are valid), with the latter now introducing potential concurrency issues (#118) since lazy loading (#111) makes construction suspend on an awaited `Load()`, where this previously completed synchronously, running each branch to completion before the next. This will allow multiple branches to construct the same topic and view model at once, an acceptable overlap `MapPath()` will now be able to distinguish from a true circular loop. --- OnTopic/Mapping/TopicMappingService.cs | 66 +++++++++++++++++--------- 1 file changed, 43 insertions(+), 23 deletions(-) diff --git a/OnTopic/Mapping/TopicMappingService.cs b/OnTopic/Mapping/TopicMappingService.cs index 9d64eba5..1e1e4c0e 100644 --- a/OnTopic/Mapping/TopicMappingService.cs +++ b/OnTopic/Mapping/TopicMappingService.cs @@ -69,12 +69,14 @@ public class TopicMappingService(ITopicRepository topicRepository, ITypeLookupSe /// Determines what associations the mapping should include, if any. /// A cache to keep track of already-mapped object instances. /// The prefix to apply to the attributes. + /// The current mapping request's path, used to detect circular references during construction. /// An instance of the dynamically determined View Model with properties appropriately mapped. private async Task MapAsync( Topic? topic, AssociationTypes associations, MappedTopicCache cache, - string? attributePrefix = null + string? attributePrefix = null, + MapPath? mapPath = null ) { /*-------------------------------------------------------------------------------------------------------------------------- @@ -99,7 +101,7 @@ public class TopicMappingService(ITopicRepository topicRepository, ITypeLookupSe /*-------------------------------------------------------------------------------------------------------------------------- | Perform mapping \-------------------------------------------------------------------------------------------------------------------------*/ - return await MapAsync(topic, viewModelType, associations, cache, attributePrefix).ConfigureAwait(false); + return await MapAsync(topic, viewModelType, associations, cache, attributePrefix, mapPath).ConfigureAwait(false); } @@ -128,13 +130,15 @@ public class TopicMappingService(ITopicRepository topicRepository, ITypeLookupSe /// Determines what associations the mapping should include, if any. /// A cache to keep track of already-mapped object instances. /// The prefix to apply to the attributes. + /// The current mapping request's path, used to detect circular references during construction. /// An instance of the dynamically determined View Model with properties appropriately mapped. private async Task MapAsync( Topic? topic, Type type, AssociationTypes associations, MappedTopicCache cache, - string? attributePrefix = null + string? attributePrefix = null, + MapPath? mapPath = null ) { /*-------------------------------------------------------------------------------------------------------------------------- @@ -251,7 +255,7 @@ public class TopicMappingService(ITopicRepository topicRepository, ITypeLookupSe foreach (var property in typeAccessor.GetMembers(MemberTypes.Property)) { if (!mappedParameters.Contains(property.Name, StringComparer.OrdinalIgnoreCase)) { - propertyQueue.Add(SetPropertyAsync(topic, target, associations, property, cache, attributePrefix, false)); + propertyQueue.Add(SetPropertyAsync(topic, target, associations, property, cache, attributePrefix, false, mapPath)); } } @@ -292,6 +296,7 @@ public class TopicMappingService(ITopicRepository topicRepository, ITypeLookupSe /// Determines what associations the mapping should include, if any. /// A cache to keep track of already-mapped object instances. /// The prefix to apply to the attributes. + /// The current mapping request's path, used to detect circular references during construction. /// /// This internal version passes a private cache of mapped objects from this run. This helps prevent problems with /// recursion in case is referred to multiple times (e.g., a Children collection with MapAsync( object target, AssociationTypes associations, MappedTopicCache cache, - string? attributePrefix = null + string? attributePrefix = null, + MapPath? mapPath = null ) { /*-------------------------------------------------------------------------------------------------------------------------- @@ -351,7 +357,7 @@ private async Task MapAsync( var typeAccessor = TypeAccessorCache.GetTypeAccessor(target.GetType()); foreach (var property in typeAccessor.GetMembers(MemberTypes.Property)) { - taskQueue.Add(SetPropertyAsync(topic, target, associations, property, cache, attributePrefix, cacheEntry is not null)); + taskQueue.Add(SetPropertyAsync(topic, target, associations, property, cache, attributePrefix, cacheEntry is not null, mapPath)); } await Task.WhenAll([.. taskQueue]).ConfigureAwait(false); @@ -374,12 +380,14 @@ private async Task MapAsync( /// Information related to the current parameter. /// A cache to keep track of already-mapped object instances. /// The prefix to apply to the attributes. + /// The current mapping request's path, used to detect circular references during construction. private async Task GetParameterAsync( Topic source, AssociationTypes associations, ParameterMetadata parameter, MappedTopicCache cache, - string? attributePrefix = null + string? attributePrefix = null, + MapPath? mapPath = null ) { /*-------------------------------------------------------------------------------------------------------------------------- @@ -403,14 +411,15 @@ private async Task MapAsync( parameter.Type, associations, cache, - configuration.AttributePrefix + attributePrefix + configuration.AttributePrefix + attributePrefix, + mapPath ).ConfigureAwait(false); } /*-------------------------------------------------------------------------------------------------------------------------- | Determine value \-------------------------------------------------------------------------------------------------------------------------*/ - var value = await GetValue(source, parameter.Type, associations, parameter, cache, attributePrefix, false).ConfigureAwait(false); + var value = await GetValue(source, parameter.Type, associations, parameter, cache, attributePrefix, false, mapPath).ConfigureAwait(false); if (value is null && parameter.IsList) { return await getList(parameter.Type).ConfigureAwait(false); @@ -430,7 +439,7 @@ private async Task MapAsync( return null; } - await PopulateTargetCollectionAsync(sourceList, targetList, parameter, cache).ConfigureAwait(false); + await PopulateTargetCollectionAsync(sourceList, targetList, parameter, cache, mapPath).ConfigureAwait(false); return targetList; @@ -452,6 +461,7 @@ private async Task MapAsync( /// A cache to keep track of already-mapped object instances. /// The prefix to apply to the attributes. /// Determines if properties not associated with associations should be mapped. + /// The current mapping request's path, used to detect circular references during construction. private async Task SetPropertyAsync( Topic source, object target, @@ -459,7 +469,8 @@ private async Task SetPropertyAsync( MemberAccessor propertyAccessor, MappedTopicCache cache, string? attributePrefix = null, - bool mapAssociationsOnly = false + bool mapAssociationsOnly = false, + MapPath? mapPath = null ) { /*-------------------------------------------------------------------------------------------------------------------------- @@ -485,7 +496,8 @@ await MapAsync( targetProperty, associations, cache, - configuration.AttributePrefix + attributePrefix + configuration.AttributePrefix + attributePrefix, + mapPath ).ConfigureAwait(false); } } @@ -494,9 +506,9 @@ await MapAsync( | Determine value \-------------------------------------------------------------------------------------------------------------------------*/ else { - var value = await GetValue(source, propertyAccessor.Type, associations, propertyAccessor, cache, attributePrefix, mapAssociationsOnly).ConfigureAwait(false); + var value = await GetValue(source, propertyAccessor.Type, associations, propertyAccessor, cache, attributePrefix, mapAssociationsOnly, mapPath).ConfigureAwait(false); if (value is null && propertyAccessor.IsList) { - await SetCollectionValueAsync(source, target, associations, propertyAccessor, cache, attributePrefix, mapAssociationsOnly).ConfigureAwait(false); + await SetCollectionValueAsync(source, target, associations, propertyAccessor, cache, attributePrefix, mapAssociationsOnly, mapPath).ConfigureAwait(false); } else if (value != null && propertyAccessor.CanWrite) { propertyAccessor.SetValue(target, value, true); @@ -523,6 +535,7 @@ await MapAsync( /// A cache to keep track of already-mapped object instances. /// The prefix to apply to the attributes. /// Determines if properties not associated with associations should be mapped. + /// The current mapping request's path, used to detect circular references during construction. private async Task GetValue( Topic source, Type targetType, @@ -530,7 +543,8 @@ await MapAsync( ItemMetadata itemMetadata, MappedTopicCache cache, string? attributePrefix = "", - bool mapAssociationsOnly = false + bool mapAssociationsOnly = false, + MapPath? mapPath = null ) { /*-------------------------------------------------------------------------------------------------------------------------- @@ -562,7 +576,7 @@ await MapAsync( } else if (configuration.GetCompositeAttributeKey(attributePrefix) is "Parent") { if (associations.HasFlag(AssociationTypes.Parents) && source.Parent is not null) { - value = await GetTopicReferenceAsync(source.Parent, targetType, itemMetadata, cache).ConfigureAwait(false); + value = await GetTopicReferenceAsync(source.Parent, targetType, itemMetadata, cache, mapPath).ConfigureAwait(false); } } else if (configuration.MapToParent) { @@ -571,7 +585,7 @@ await MapAsync( else if (itemMetadata.Type.IsClass && associations.HasFlag(AssociationTypes.References)) { var topicReference = await getTopicReference().ConfigureAwait(false); if (topicReference is not null) { - value = await GetTopicReferenceAsync(topicReference, targetType, itemMetadata, cache).ConfigureAwait(false); + value = await GetTopicReferenceAsync(topicReference, targetType, itemMetadata, cache, mapPath).ConfigureAwait(false); } } @@ -730,6 +744,7 @@ await MapAsync( /// A cache to keep track of already-mapped object instances. /// The prefix to apply to the attributes. /// Determines if properties not associated with associations should be mapped. + /// The current mapping request's path, used to detect circular references during construction. private async Task SetCollectionValueAsync( Topic source, object target, @@ -737,7 +752,8 @@ private async Task SetCollectionValueAsync( MemberAccessor memberAccessor, MappedTopicCache cache, string? attributePrefix, - bool mapAssociationsOnly + bool mapAssociationsOnly, + MapPath? mapPath = null ) { /*-------------------------------------------------------------------------------------------------------------------------- @@ -768,7 +784,7 @@ bool mapAssociationsOnly /*-------------------------------------------------------------------------------------------------------------------------- | Map the topics from the source collection, and add them to the target collection \-------------------------------------------------------------------------------------------------------------------------*/ - await PopulateTargetCollectionAsync(sourceList, targetList, memberAccessor, cache).ConfigureAwait(false); + await PopulateTargetCollectionAsync(sourceList, targetList, memberAccessor, cache, mapPath).ConfigureAwait(false); } @@ -922,11 +938,13 @@ IList getCollection(CollectionType collection, Func contain /// The target to add the mapped objects to. /// The with details about the property's attributes. /// A cache to keep track of already-mapped object instances. + /// The current mapping request's path, used to detect circular references during construction. private async Task PopulateTargetCollectionAsync( IList sourceList, IList targetList, ItemMetadata itemMetadata, - MappedTopicCache cache + MappedTopicCache cache, + MapPath? mapPath = null ) { /*-------------------------------------------------------------------------------------------------------------------------- @@ -981,7 +999,7 @@ configuration.ContentTypeFilter is not null && if (!typeof(Topic).IsAssignableFrom(listType)) { var mappingType = GetValidatedMappingType(configuration.MapAs, listType)?? GetValidatedMappingType(childTopic, listType); if (mappingType is not null) { - taskQueue.Add(MapAsync(childTopic, mappingType, configuration.IncludeAssociations, cache)); + taskQueue.Add(MapAsync(childTopic, mappingType, configuration.IncludeAssociations, cache, mapPath: mapPath)); } } else { @@ -1055,11 +1073,13 @@ void addToList(object dto) { /// The expected for the mapped . /// The with details about the item's attributes. /// A cache to keep track of already-mapped object instances. + /// The current mapping request's path, used to detect circular references during construction. private async Task GetTopicReferenceAsync( Topic source, Type targetType, ItemMetadata itemMetadata, - MappedTopicCache cache + MappedTopicCache cache, + MapPath? mapPath = null ) { /*-------------------------------------------------------------------------------------------------------------------------- @@ -1083,7 +1103,7 @@ MappedTopicCache cache var mappingType = GetValidatedMappingType(configuration.MapAs, targetType)?? GetValidatedMappingType(source, targetType); if (mappingType is not null) { - topicDto = await MapAsync(source, mappingType, configuration.IncludeAssociations, cache).ConfigureAwait(false); + topicDto = await MapAsync(source, mappingType, configuration.IncludeAssociations, cache, mapPath: mapPath).ConfigureAwait(false); } /*-------------------------------------------------------------------------------------------------------------------------- From 5a6b8a9abd0f9704187217fee7c3672f8eff924c Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Mon, 3 Aug 2026 19:14:14 -0700 Subject: [PATCH 304/337] =?UTF-8?q?Added=20`TryGetValue(=E2=80=A6,=20inclu?= =?UTF-8?q?deInitializing)`=20param?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The new `includeInitializing` parameter optionally allows the caller to specifically request a cached entry that hasn't yet been initialized. Once implemented, this will allow a caller to check the initialization and, if it's in the process of initializing, `await` the new `Completion` property on the `MappedTopicCacheEntry` (7a5bd2c2), thus preventing the need for two calls to map the same topic to the same view model from constructing two distinct view models, and thus satisfying a core requirement for #118. --- OnTopic/Mapping/Internal/MappedTopicCache.cs | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/OnTopic/Mapping/Internal/MappedTopicCache.cs b/OnTopic/Mapping/Internal/MappedTopicCache.cs index 11be1494..f73539ea 100644 --- a/OnTopic/Mapping/Internal/MappedTopicCache.cs +++ b/OnTopic/Mapping/Internal/MappedTopicCache.cs @@ -32,9 +32,23 @@ internal sealed class MappedTopicCache { /// The associated with the cache entry. /// The that the has been mapped to. /// The containing the cached instance and metadata. + /// + /// Determines whether an entry that is still should be returned. Left + /// false by default, so callers continue to see only fully constructed entries; set true only by callers who + /// are prepared to distinguish a constructor cycle from sibling concurrency and to await an in-progress entry's completion. + /// /// Returns true if a cached entry could be found, and otherwise false. - internal bool TryGetValue(int topicId, Type type, [NotNullWhen(true)] out MappedTopicCacheEntry? cacheEntry) { - if (_cache.TryGetValue(GetCacheKey(topicId, type), out var existingCacheEntry) && !existingCacheEntry.IsInitializing) { + internal bool TryGetValue( + int topicId, + Type type, + [NotNullWhen(true)] + out MappedTopicCacheEntry? cacheEntry, + bool includeInitializing = false + ) { + if ( + _cache.TryGetValue(GetCacheKey(topicId, type), out var existingCacheEntry) && + (includeInitializing || !existingCacheEntry.IsInitializing) + ) { cacheEntry = existingCacheEntry; return true; }; From ee9a9a51a1ff9c5e706b3f730d0e8f8729bbf26f Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Mon, 3 Aug 2026 19:26:52 -0700 Subject: [PATCH 305/337] Wire-up `Complete()` in `Register()` When calling `MappedTopicCache.Register()`, call the new `MappedTopicCacheEntry.Complete()` method (7a5bd2c2). As part of this, also allow `Complete()` to set the `IsInitializing`, `MappedTopic`, and the initial state for `Associations` using its payload, which allows us to entirely remove the setters for `IsInitializing` and `MappedTopic`. That forces callers to use the `Completion` semantics that are required for concurrency of the `TopicMappingService` (#118). --- OnTopic/Mapping/Internal/MappedTopicCache.cs | 13 +++---------- .../Mapping/Internal/MappedTopicCacheEntry.cs | 19 +++++++++++++------ 2 files changed, 16 insertions(+), 16 deletions(-) diff --git a/OnTopic/Mapping/Internal/MappedTopicCache.cs b/OnTopic/Mapping/Internal/MappedTopicCache.cs index f73539ea..cccc47c4 100644 --- a/OnTopic/Mapping/Internal/MappedTopicCache.cs +++ b/OnTopic/Mapping/Internal/MappedTopicCache.cs @@ -73,21 +73,14 @@ internal void Register(int topicId, AssociationTypes associations, object viewMo \-------------------------------------------------------------------------------------------------------------------------*/ var type = viewModel.GetType(); var cacheKey = GetCacheKey(topicId, type); - var cacheEntry = new MappedTopicCacheEntry() { - MappedTopic = viewModel, - Associations = associations - }; + var cacheEntry = new MappedTopicCacheEntry(); /*-------------------------------------------------------------------------------------------------------------------------- | Get or add entry \-------------------------------------------------------------------------------------------------------------------------*/ - if (topicId > 0 && !type.Equals(typeof(object))) { + if (topicId > 0 && type != typeof(object)) { cacheEntry = _cache.GetOrAdd(cacheKey, cacheEntry); - if (cacheEntry.IsInitializing) { - cacheEntry.IsInitializing = false; - cacheEntry.MappedTopic = viewModel; - cacheEntry.Associations = associations; - } + cacheEntry.Complete(viewModel, associations); } } diff --git a/OnTopic/Mapping/Internal/MappedTopicCacheEntry.cs b/OnTopic/Mapping/Internal/MappedTopicCacheEntry.cs index b5fae15e..b9745a4c 100644 --- a/OnTopic/Mapping/Internal/MappedTopicCacheEntry.cs +++ b/OnTopic/Mapping/Internal/MappedTopicCacheEntry.cs @@ -36,7 +36,13 @@ internal sealed class MappedTopicCacheEntry { /// /// Provides a reference to the mapped object. /// - internal object MappedTopic { get; set; } = null!; + /// + /// Assigned only by , which also settles the task, + /// so the mapped instance is never published outside the completion cycle. This topic is fully constructed, but may not yet + /// have all of its properties mapped; the only prevents two instances of + /// the same view model from being constructed, but doesn't guarantee that mapping is finished. + /// + internal object MappedTopic { get; private set; } = null!; /*============================================================================================================================ | PROPERTY: IS INITIALIZING @@ -47,11 +53,12 @@ internal sealed class MappedTopicCacheEntry { /// /// The property allows an entry to be pre-cached prior to the object being completed. This /// allows the to detect circular references within the object initialization sequence. - /// This is important because, unlikely property mapping where a cached reference can be returned, a circular reference - /// in constructor mapping is expected to throw an exception. By registering that an object is being initialized, the - /// is able to detect circuluar references during constructor mapping. + /// This is important because, unlike property mapping where a cached reference can be returned, a circular reference in + /// constructor mapping is expected to throw an exception. It is derived from the task rather than + /// stored, so a faulted entry remains initializing, ensuring an awaiting pass observes the fault instead of a null . /// - internal bool IsInitializing { get; set; } + internal bool IsInitializing => !_completionSource.Task.IsCompletedSuccessfully; /*============================================================================================================================ | PROPERTY: ASSOCIATIONS @@ -103,7 +110,7 @@ internal sealed class MappedTopicCacheEntry { /// /// This is the mutating counterpart to : It adds any associations /// that aren't already covered, and reports which ones were added back to the caller so the caller knows which associations - /// to process. Because the delta is calculated and saved under a single lock, two concurrent passes over the same cached + /// to process. Because the delta is calculated and saved under a single lock, two concurrent passes over the same cached /// instance receive disjoint results, ensuring each association is mapped by exactly one caller. A caller that receives /// has nothing left to map and should return the cached instance. /// From b197889ebe865538c8882f1af95c6a801431cf83 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Mon, 3 Aug 2026 20:22:52 -0700 Subject: [PATCH 306/337] Wire-up `Fault()` in `MapAsync()` When calling (the final private overload of) `TopicMappingService.MapAsync()`, call the new `MappedTopicCacheEntry.Fault()` method (7a5bd2c2) if there's any issue constructing the new view model. This notifies callers that the `Completion` is finished, yet also that the mapped object isn't initialized (i.e., `!IsInitialized`). This looks like a big change, but it's mostly an indentation change, as it requires wrapping the construction of the view model into a `try` block, then calling `Fetch()` within a new `catch` block. As such, most of the git diff is just the preexisting code being indented inside of the `try` block. This helps ensure that one topic can be concurrently mapped to the same view model without interference (#118). --- OnTopic/Mapping/TopicMappingService.cs | 125 +++++++++++++++---------- 1 file changed, 74 insertions(+), 51 deletions(-) diff --git a/OnTopic/Mapping/TopicMappingService.cs b/OnTopic/Mapping/TopicMappingService.cs index 1e1e4c0e..fbd067bd 100644 --- a/OnTopic/Mapping/TopicMappingService.cs +++ b/OnTopic/Mapping/TopicMappingService.cs @@ -182,70 +182,93 @@ public class TopicMappingService(ITopicRepository topicRepository, ITypeLookupSe \-------------------------------------------------------------------------------------------------------------------------*/ cache.Preregister(topic.Id, type); - /*-------------------------------------------------------------------------------------------------------------------------- - | Handle AttributeDictionary constructor - >------------------------------------------------------------------------------------------------------------------------- - | A model may optionally expose a constructor with a single parameter accepting an AttributeDictionary. In this scenario, - | the TopicMappingService may optionally pass a lightweight AttributeDictionary, allowing the model's constructor to - | populate scalar values, instead of relying on reflection. - \-------------------------------------------------------------------------------------------------------------------------*/ - if (parameters.Count is 1 && parameters[0].Type == typeof(AttributeDictionary)) { - - // This strategy is only performant if there are quite a several scalar properties and they are well-covered by the - // attributes. As a fast heuristic to evaluate this, we expect five or more attributes and three or more compatible - // properties. In practice, this should be benefitial with any more than mapped attributes, but we also expect that most - // topics will have 2-3 excluded or unmapped attributes (e.g., Title, LastModified). With models, we can be a bit more - // intelligent, by excluding any members that are likely compatible with Topic properties, thus exluding e.g., Id, Key, - // WebPath, etc. This doesn't guarantee that the attributes map to the properties, but a more accurate evaluation would - // undermine the performance benefits of this optimization. - if (topic.Attributes.Count >= 5 && properties.Count(p => !p.MaybeCompatible) >= 3) { - var attributes = topic.Attributes.AsAttributeDictionary(true); - arguments[0] = attributes; - attributeArguments = attributes; - } - else { - parameters = new(); - arguments = []; - } } /*-------------------------------------------------------------------------------------------------------------------------- - | Handle other constructors - >------------------------------------------------------------------------------------------------------------------------- - | A model may optionally expose a constructor with multiple parameters, which can be defined via reflection in the same - | way as properties would be. This is especially useful for records using the positional syntax (i.e., where properties - | are defined using the constructor). This also, optionally, provides the model with more control, where needed, over how - | it's constructed. - \-------------------------------------------------------------------------------------------------------------------------*/ - else { + | Construct and register the target + >--------------------------------------------------------------------------------------------------------------------------- + | Only the construction span is guarded, so the entry's completion is always settled: cache.Register() settles it on + | success and the catch faults it on failure, so a pass awaiting this entry observes the failure instead of hanging. + | Property mapping runs afterward, outside the guard, since the entry is already settled by then. + \-------------------------------------------------------------------------------------------------------------------------*/ + object? target; + + try { + + /*------------------------------------------------------------------------------------------------------------------------ + | Handle AttributeDictionary constructor + >------------------------------------------------------------------------------------------------------------------------- + | A model may optionally expose a constructor with a single parameter accepting an AttributeDictionary. In this scenario, + | the TopicMappingService may optionally pass a lightweight AttributeDictionary, allowing the model's constructor to + | populate scalar values, instead of relying on reflection. + \-----------------------------------------------------------------------------------------------------------------------*/ + if (parameters.Count is 1 && parameters[0].Type == typeof(AttributeDictionary)) { + + // This strategy is only performant if there are quite a several scalar properties and they are well-covered by the + // attributes. As a fast heuristic to evaluate this, we expect five or more attributes and three or more compatible + // properties. In practice, this should be benefitial with any more than mapped attributes, but we also expect that most + // topics will have 2-3 excluded or unmapped attributes (e.g., Title, LastModified). With models, we can be a bit more + // intelligent, by excluding any members that are likely compatible with Topic properties, thus exluding e.g., Id, Key, + // WebPath, etc. This doesn't guarantee that the attributes map to the properties, but a more accurate evaluation would + // undermine the performance benefits of this optimization. + if (topic.Attributes.Count >= 5 && properties.Count(p => !p.MaybeCompatible) >= 3) { + var attributes = topic.Attributes.AsAttributeDictionary(true); + arguments[0] = attributes; + attributeArguments = attributes; + } + else { + parameters = new(); + arguments = []; + } - foreach (var parameter in parameters) { - parameterQueue.Add(parameter.ParameterInfo.Position, GetParameterAsync(topic, associations, parameter, cache, attributePrefix)); } - await Task.WhenAll(parameterQueue.Values).ConfigureAwait(false); + /*------------------------------------------------------------------------------------------------------------------------ + | Handle other constructors + >------------------------------------------------------------------------------------------------------------------------- + | A model may optionally expose a constructor with multiple parameters, which can be defined via reflection in the same + | way as properties would be. This is especially useful for records using the positional syntax (i.e., where properties + | are defined using the constructor). This also, optionally, provides the model with more control, where needed, over how + | it's constructed. + \-----------------------------------------------------------------------------------------------------------------------*/ + else { + + foreach (var parameter in parameters) { + parameterQueue.Add(parameter.ParameterInfo.Position, GetParameterAsync(topic, associations, parameter, cache, attributePrefix, mapPath)); + } + + await Task.WhenAll(parameterQueue.Values).ConfigureAwait(false); + + foreach (var parameter in parameterQueue) { + arguments[parameter.Key] = await parameter.Value.ConfigureAwait(false); + } - foreach (var parameter in parameterQueue) { - arguments[parameter.Key] = await parameter.Value.ConfigureAwait(false); } - } + /*------------------------------------------------------------------------------------------------------------------------ + | Initialize object + \-----------------------------------------------------------------------------------------------------------------------*/ + target = Activator.CreateInstance(type, arguments); - /*-------------------------------------------------------------------------------------------------------------------------- - | Initialize object - \-------------------------------------------------------------------------------------------------------------------------*/ - target = Activator.CreateInstance(type, arguments); + Contract.Assume( + target, + $"The target type '{type}' could not be properly constructed, as required to map the topic '{topic.GetUniqueKey()}'." + ); - Contract.Assume( - target, - $"The target type '{type}' could not be properly constructed, as required to map the topic '{topic.GetUniqueKey()}'." - ); + /*------------------------------------------------------------------------------------------------------------------------ + | Cache object + \-----------------------------------------------------------------------------------------------------------------------*/ + cache.Register(topic.Id, associations, target); - /*-------------------------------------------------------------------------------------------------------------------------- - | Cache object - \-------------------------------------------------------------------------------------------------------------------------*/ - cache.Register(topic.Id, associations, target); + } + + // Construction failed before the entry was registered, so fault it; a concurrent pass awaiting this entry's completion then + // observes the failure instead of hanging on a map that will never complete + catch (Exception exception) { + entry.Fault(exception); + throw; + } /*-------------------------------------------------------------------------------------------------------------------------- | Loop through properties, mapping each one From 1334a2bb7a977d47b124c8e8a795d4cbf9fdec2f Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Mon, 3 Aug 2026 21:25:53 -0700 Subject: [PATCH 307/337] Introduce `resolveCachedEntry()` MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The new `resolveCachedEntry()` local function to centralize the creation, patching, and lookup of cached entries in response to `MapAsync()` requests. Notably, it enables awaiting for an existing construction of a topic to the same view model for independent siblings via the new `Completion` semantics ((7a5bd2c2) that were previously integrated (ee9a9a51, b197889e) by relying on the new `TryGetValue(…, includeInitializing)` parameter (5a6b8a9a) to lookup a pending constructor. It also calculates the `MapPath` class (61b1487c, b42673a4) to recognize circular constructor loops, and thus moves the exception handling for that out of `Preregister()`, so that it won't hang the thread. This addresses the biggest issue with regards to the concurrency handling in the `TopicMappingService` in response to the lazy-loading concerns (#118), though there remain some smaller pieces, plus of course unit testing of these updates. --- OnTopic/Mapping/Internal/MappedTopicCache.cs | 23 +++--- OnTopic/Mapping/TopicMappingService.cs | 77 ++++++++++++++++---- 2 files changed, 71 insertions(+), 29 deletions(-) diff --git a/OnTopic/Mapping/Internal/MappedTopicCache.cs b/OnTopic/Mapping/Internal/MappedTopicCache.cs index cccc47c4..4481f4d0 100644 --- a/OnTopic/Mapping/Internal/MappedTopicCache.cs +++ b/OnTopic/Mapping/Internal/MappedTopicCache.cs @@ -90,34 +90,31 @@ internal void Register(int topicId, AssociationTypes associations, object viewMo \---------------------------------------------------------------------------------------------------------------------------*/ /// /// Attempts to preregister a for a that is in the process of - /// being mapped to . + /// being mapped to , returning the entry along with whether this call created it. /// + /// + /// The returned IsNew flag is true when this call established the entry, and therefore owns its construction; + /// it is false when a concurrent pass had already preregistered the same and , in which case the returned entry is that concurrent pass's entry. + /// /// The associated with the cache entry. /// The that the is being mapped to. - internal MappedTopicCacheEntry Preregister(int topicId, Type type) { + internal (MappedTopicCacheEntry Entry, bool IsNew) Preregister(int topicId, Type type) { /*-------------------------------------------------------------------------------------------------------------------------- | Construct cache entry \-------------------------------------------------------------------------------------------------------------------------*/ var cacheKey = GetCacheKey(topicId, type); - var cacheEntry = new MappedTopicCacheEntry() { - IsInitializing = true - }; + var cacheEntry = new MappedTopicCacheEntry(); /*-------------------------------------------------------------------------------------------------------------------------- | Get or add entry \-------------------------------------------------------------------------------------------------------------------------*/ if (topicId > 0 && !type.Equals(typeof(object))) { var existingCacheEntry = _cache.GetOrAdd(cacheKey, cacheEntry); - if (existingCacheEntry != cacheEntry) { - throw new TopicMappingException( - $"An attempt has been made to map '{topicId}' to a {type.Name} has resulted in a circular reference during the " + - $"construction of the {type.Name} instance. This is not allowed. Circular must be be mapped as properties, not " + - $"as constructor parameters, so that cached entries can be returned." - ); - } + return (existingCacheEntry, existingCacheEntry == cacheEntry); } - return cacheEntry; + return (cacheEntry, true); } diff --git a/OnTopic/Mapping/TopicMappingService.cs b/OnTopic/Mapping/TopicMappingService.cs index fbd067bd..f14c333f 100644 --- a/OnTopic/Mapping/TopicMappingService.cs +++ b/OnTopic/Mapping/TopicMappingService.cs @@ -150,16 +150,14 @@ public class TopicMappingService(ITopicRepository topicRepository, ITypeLookupSe /*-------------------------------------------------------------------------------------------------------------------------- | Handle cached objects + >--------------------------------------------------------------------------------------------------------------------------- + | Included entries that are still initializing, so a circular constructor reference (i.e., the same topic and type are + | already under construction higher up the current chain) can be distinguished from concurrent siblings (i.e., two + | independent branches mapping the same topic and type at once). The former throws; the latter awaits for the first one to + | finish construction and then uses the same cached view model. \-------------------------------------------------------------------------------------------------------------------------*/ - var target = (object?)null; - - if (cache.TryGetValue(topic.Id, type, out var cacheEntry)) { - target = cacheEntry.MappedTopic; - if (cacheEntry.GetMissingAssociations(associations) == AssociationTypes.None) { - return target; - } - //Call MapAsync() with target object to map missing attributes - return await MapAsync(topic, target, associations, cache, attributePrefix).ConfigureAwait(false); + if (cache.TryGetValue(topic.Id, type, out var cacheEntry, includeInitializing: true)) { + return await resolveCachedEntry(cacheEntry, mapPath).ConfigureAwait(false); } /*-------------------------------------------------------------------------------------------------------------------------- @@ -175,16 +173,28 @@ public class TopicMappingService(ITopicRepository topicRepository, ITypeLookupSe /*-------------------------------------------------------------------------------------------------------------------------- | Pre-cache entry >------------------------------------------------------------------------------------------------------------------------- - | In property mapping, we deal with circular references by returning a cached reference. That isn't practical with - | circular references in constructor mapping. To help avoid these, we register a pre-cache entry as IsInitializing, but - | without a mapped object; the TopicMappingCache is expected to throw an exception if an attempt to map that topic to that - | type occurs again prior to the constructor mapping being completed. + | In property mapping, we deal with circular references by returning a cached reference. That isn't practical with circular + | references in constructor mapping. To help avoid these, we register a pre-cache entry as IsInitializing, but without a + | mapped object. If a concurrent sibling wins the race to preregister the same topic and view model type, we defer to its + | result rather than constructing a duplicate. If we're constructing the same topic and view model type as we're already in + | the middle of constructing further up the MapPath chain, however, that's a true circular construction reference, handled + | via the local resolveCachedEntry() function. \-------------------------------------------------------------------------------------------------------------------------*/ - cache.Preregister(topic.Id, type); - + var (entry, isNew) = cache.Preregister(topic.Id, type); + if (!isNew) { + return await resolveCachedEntry(entry, mapPath).ConfigureAwait(false); } + /*-------------------------------------------------------------------------------------------------------------------------- + | Establish mapping path chain + >--------------------------------------------------------------------------------------------------------------------------- + | Now that this pass owns constructing a new view model, establish the initial topic and view model type in the MapPath, so + | any nested mapping that arrives back to the same pair while it is still initializing is recognized as a true circular + | constructor reference rather than harmless concurrency among independent siblings. + \-------------------------------------------------------------------------------------------------------------------------*/ + mapPath = new(topic.Id, type, mapPath); + /*-------------------------------------------------------------------------------------------------------------------------- | Construct and register the target >--------------------------------------------------------------------------------------------------------------------------- @@ -289,6 +299,41 @@ public class TopicMappingService(ITopicRepository topicRepository, ITypeLookupSe \-------------------------------------------------------------------------------------------------------------------------*/ return target; + /*-------------------------------------------------------------------------------------------------------------------------- + | Resolve cached entry + >--------------------------------------------------------------------------------------------------------------------------- + | Returns a cached instance, expanding it with any missing associations when needed. If the entry is still initializing, it + | is either a true circular constructor reference on the current path (in which we throw an exception) or it's concurrent + | mapping of two independent siblings of the same topic and view model (in which we simply await its completion, then + | return the shared instance as a normal cache hit). + \-------------------------------------------------------------------------------------------------------------------------*/ + async Task resolveCachedEntry(MappedTopicCacheEntry pendingEntry, MapPath? path) { + + // Distinguish a constructor cycle from sibling concurrency for an entry that is still being constructed + if (pendingEntry.IsInitializing) { + if (path?.Contains(topic.Id, type) == true) { + throw new TopicMappingException( + $"A circular reference was detected while constructing the '{type.Name}' instance for topic '{topic.Id}'. Circular " + + $"references must be mapped as properties, not as constructor parameters, so that a cached instance can be returned." + ); + } + // Not on the current path: a concurrent sibling owns construction, so await its completion before resolving. A mutual + // constructor cycle split across two concurrently mapped branches is the one case this cannot distinguish and would + // deadlock; such cycles are unsupported, and still throw when reached from a single branch via the path check above. + await pendingEntry.Completion.ConfigureAwait(false); + } + + // Return the cached instance as-is when it already covers the requested associations + var cachedTarget = pendingEntry.MappedTopic; + if (pendingEntry.GetMissingAssociations(associations) is AssociationTypes.None) { + return cachedTarget; + } + + // Otherwise expand the cached instance, mapping only the missing associations + return await MapAsync(topic, cachedTarget, associations, cache, attributePrefix, path).ConfigureAwait(false); + + } + } /*============================================================================================================================ @@ -353,7 +398,7 @@ private async Task MapAsync( /*-------------------------------------------------------------------------------------------------------------------------- | Handle cached objects - >------------------------------------------------------------------------------------------------------------------------- + >--------------------------------------------------------------------------------------------------------------------------- | If the cache contains an entry, check to make sure it includes all of the requested associations. If it does, return it. | Otherwise, add the missing associations to the cache entry and map only the subset this pass added, so that a concurrent | pass doesn't remap the same associations. From 28f0b07cafca253557c62d9d731e1d1657432b56 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Mon, 3 Aug 2026 23:19:53 -0700 Subject: [PATCH 308/337] Added unit tests for completion semantics These tests evaluate the new completion semantics (7a5bd2c2), including `Complete()` and `Fault()` as well as the `Completion` and `IsInitializing` (ee9a9a51) properties. This contributes to testing of the `TopicMappingService`'s concurrency infrastructure (#118), and specifically around avoiding concurrent construction of new topic view models via the `MappedTopicCacheEntry`. --- OnTopic.Tests/TopicMappingServiceTest.cs | 75 ++++++++++++++++++++++++ 1 file changed, 75 insertions(+) diff --git a/OnTopic.Tests/TopicMappingServiceTest.cs b/OnTopic.Tests/TopicMappingServiceTest.cs index 8a8fd20f..ac9145ab 100644 --- a/OnTopic.Tests/TopicMappingServiceTest.cs +++ b/OnTopic.Tests/TopicMappingServiceTest.cs @@ -797,6 +797,81 @@ public void MappedTopicCacheEntry_AddMissingAssociations_ReturnsNewlyAdded() { } + /*============================================================================================================================ + | TEST: MAPPED TOPIC CACHE ENTRY: IS INITIALIZING: REFLECTS COMPLETION STATE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Establishes a set of instances and confirms that is derived from the completion state: A fresh entry is initializing, a + /// completed entry is not, and a faulted entry remains initializing so an awaiting pass observes the fault instead of a + /// null instance. + /// + [Fact] + public void MappedTopicCacheEntry_IsInitializing_ReflectsCompletionState() { + + var completed = new MappedTopicCacheEntry(); + var faulted = new MappedTopicCacheEntry(); + + Assert.True(completed.IsInitializing); + Assert.True(faulted.IsInitializing); + + completed.Complete(new EmptyViewModel(), AssociationTypes.None); + faulted.Fault(new InvalidOperationException()); + + Assert.False(completed.IsInitializing); + Assert.True(faulted.IsInitializing); + + // Observe the faulted task so its exception isn't surfaced as unobserved + Assert.NotNull(faulted.Completion.Exception); + + } + + /*============================================================================================================================ + | TEST: MAPPED TOPIC CACHE ENTRY: COMPLETION: SETTLES ON COMPLETE OR FAULT + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Establishes a pair of instances and confirms that resolves when the entry is completed, and throws the recorded exception when the + /// entry is faulted, so that a second pass awaiting the entry is always released rather than left hanging. + /// + [Fact] + public async Task MappedTopicCacheEntry_Completion_SettlesOnCompleteOrFault() { + + var completed = new MappedTopicCacheEntry(); + var faulted = new MappedTopicCacheEntry(); + + completed.Complete(new EmptyViewModel(), AssociationTypes.None); + faulted.Fault(new InvalidOperationException("Construction failed.")); + + Assert.True(completed.Completion.IsCompletedSuccessfully); + await Assert.ThrowsAsync(async () => await faulted.Completion.ConfigureAwait(false)); + + } + + /*============================================================================================================================ + | TEST: MAPPED TOPIC CACHE ENTRY: COMPLETE: RETAINS FIRST RESULT + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Establishes a and confirms that only the first call takes effect: A later duplicate registration is + /// ignored, keeping both the and its stable. + /// + [Fact] + public void MappedTopicCacheEntry_Complete_RetainsFirstResult() { + + var entry = new MappedTopicCacheEntry(); + var first = new EmptyViewModel(); + var second = new EmptyViewModel(); + + entry.Complete(first, AssociationTypes.Children); + entry.Complete(second, AssociationTypes.Parents); + + Assert.Same(first, entry.MappedTopic); + Assert.Equal(AssociationTypes.Children, entry.Associations); + + } + /*============================================================================================================================ | TEST: MAP: RELATIONSHIPS: RETURNS MAPPED MODEL \---------------------------------------------------------------------------------------------------------------------------*/ From a64b1f81c7a77cbb322e0587ead7dbd93a642e5a Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Mon, 3 Aug 2026 23:22:09 -0700 Subject: [PATCH 309/337] Added unit test for `MapPath.Contains()` This provides a unit test for the new `MapPath` data container (b42673a4) and, specifically, it's `Contain()` method, testing a similar situation as implemented in `resolveCacheEntry()` (1334a2bb). This contributes to testing of the `TopicMappingService`'s concurrency infrastructure (#118), and specifically around avoiding concurrent construction of new topic view models via the `MappedTopicCacheEntry`. --- OnTopic.Tests/TopicMappingServiceTest.cs | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/OnTopic.Tests/TopicMappingServiceTest.cs b/OnTopic.Tests/TopicMappingServiceTest.cs index ac9145ab..1486cdd1 100644 --- a/OnTopic.Tests/TopicMappingServiceTest.cs +++ b/OnTopic.Tests/TopicMappingServiceTest.cs @@ -872,6 +872,27 @@ public void MappedTopicCacheEntry_Complete_RetainsFirstResult() { } + /*============================================================================================================================ + | TEST: MAP PATH: CONTAINS: DETECTS PAIRS ON PATH + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Establishes a two-frame and confirms that recognizes a + /// topic and view model type pair anywhere on the path, whether at the current frame or an ancestor, while rejecting pairs + /// that are not on the path, including one whose topic identifier matches but whose type does not. + /// + [Fact] + public void MapPath_Contains_DetectsPairsOnPath() { + + var root = new MapPath(1, typeof(EmptyViewModel), null); + var child = new MapPath(2, typeof(KeyOnlyTopicViewModel), root); + + Assert.True(child.Contains(2, typeof(KeyOnlyTopicViewModel))); + Assert.True(child.Contains(1, typeof(EmptyViewModel))); + Assert.False(child.Contains(3, typeof(EmptyViewModel))); + Assert.False(child.Contains(1, typeof(KeyOnlyTopicViewModel))); + + } + /*============================================================================================================================ | TEST: MAP: RELATIONSHIPS: RETURNS MAPPED MODEL \---------------------------------------------------------------------------------------------------------------------------*/ From dbb47987745c668ad54acb33ef0cc779dff06fe4 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 4 Aug 2026 00:38:41 -0700 Subject: [PATCH 310/337] Introduced `CircularConstructorTopicViewModel` This will be used in a new unit test to confirm that the circular constructor reference detection, including the completion semantics (7a5bd2c2, ee9a9a51, b197889e, 5a6b8a9a) and `MapPath` tracking (b42673a4, 61b1487c) as implemented in `resolveCachedEntry()` (1334a2bb). This contributes to testing of the `TopicMappingService`'s concurrency infrastructure (#118), and specifically around avoiding concurrent construction of new topic view models via the `MappedTopicCacheEntry`. --- .../TestDoubles/FakeViewModelLookupService.cs | 1 + .../CircularConstructorTopicViewModel.cs | 34 +++++++++++++++++++ 2 files changed, 35 insertions(+) create mode 100644 OnTopic.Tests/ViewModels/CircularConstructorTopicViewModel.cs diff --git a/OnTopic.Tests/TestDoubles/FakeViewModelLookupService.cs b/OnTopic.Tests/TestDoubles/FakeViewModelLookupService.cs index 1f24a195..e7b7a791 100644 --- a/OnTopic.Tests/TestDoubles/FakeViewModelLookupService.cs +++ b/OnTopic.Tests/TestDoubles/FakeViewModelLookupService.cs @@ -35,6 +35,7 @@ public FakeViewModelLookupService() { Add(typeof(AmbiguousRelationTopicViewModel)); Add(typeof(AscendentSpecializedTopicViewModel)); Add(typeof(AscendentTopicViewModel)); + Add(typeof(CircularConstructorTopicViewModel)); Add(typeof(CircularTopicViewModel)); Add(typeof(ConstructedTopicViewModel)); Add(typeof(DefaultValueTopicViewModel)); diff --git a/OnTopic.Tests/ViewModels/CircularConstructorTopicViewModel.cs b/OnTopic.Tests/ViewModels/CircularConstructorTopicViewModel.cs new file mode 100644 index 00000000..ded41685 --- /dev/null +++ b/OnTopic.Tests/ViewModels/CircularConstructorTopicViewModel.cs @@ -0,0 +1,34 @@ +/*============================================================================================================================== +| Author Ignia, LLC +| Client Ignia, LLC +| Project Topics Library +\=============================================================================================================================*/ +using OnTopic.Mapping; + +namespace OnTopic.Tests.ViewModels; + +/*============================================================================================================================== +| VIEW MODEL: CIRCULAR CONSTRUCTOR TOPIC +\-----------------------------------------------------------------------------------------------------------------------------*/ +/// +/// Provides a strongly typed data transfer object, implemented as a positional record, for testing constructor mapping +/// of a topic reference that may form a circular reference. +/// +/// +/// +/// Unlike , which expresses its circular reference through settable properties, this +/// model maps its reference through a positional constructor parameter on a record. This allows the to be exercised for two distinct behaviors: A non-cyclic reference should map successfully, +/// while a true self-reference should be detected as a constructor cycle and throw a , +/// since a partially constructed instance cannot be returned from a constructor. +/// +/// +/// This is a sample class intended for test purposes only; it is not designed for use in a production environment. +/// +/// +/// The key of the mapped topic. +/// An optional reference to another . +public record CircularConstructorTopicViewModel( + string Key, + [Include(AssociationTypes.References)] CircularConstructorTopicViewModel? Self +); \ No newline at end of file From dc88d41d6a29063aef5612414fd66fb31e8decf1 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 4 Aug 2026 00:43:42 -0700 Subject: [PATCH 311/337] Added unit test for positional constructor mapping Added a unit test that confirms that the ability to map constructor parameters (#35) succeeds on a record using a positional constructor. This was always the primary use case for that capability, but it wasn't explicitly tested via any prior unit tests. While this isn't directly related to testing concurrency with the `TopicMappingService` (#118), it does reuse the new `CircularConstructorTopicViewModel` (dbb47987) that was introduced for those tests, and this test is introduced first to ensure that base functionality works before I introduce a real test for evaluating the circular constructor reference. --- OnTopic.Tests/TopicMappingServiceTest.cs | 29 ++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/OnTopic.Tests/TopicMappingServiceTest.cs b/OnTopic.Tests/TopicMappingServiceTest.cs index 1486cdd1..51f8d0dd 100644 --- a/OnTopic.Tests/TopicMappingServiceTest.cs +++ b/OnTopic.Tests/TopicMappingServiceTest.cs @@ -467,6 +467,35 @@ await _mappingService.MapAsync(topic).ConfigureAwait( } + /*============================================================================================================================ + | TEST: MAP: CONSTRUCTOR (RECORD): RETURNS NEW MODEL + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Establishes a and maps a positional record whose constructor accepts a + /// non-cyclic topic reference, confirming that the reference is resolved and the record is constructed as expected. + /// + /// + /// As this is a mapping of a positional record that carries constructor parameters, it also confirms that the + /// primary constructor is correctly selected and its parameters mapped. + /// + [Fact] + public async Task Map_ConstructorRecord_ReturnsNewModel() { + + var topic = new Topic("Parent", "CircularConstructor", null, 1); + var child = new Topic("Child", "CircularConstructor", null, 2); + + topic.References.SetValue("Self", child); + + var target = await _mappingService.MapAsync(topic); + + Assert.NotNull(target); + Assert.Equal("Parent", target.Key); + Assert.NotNull(target.Self); + Assert.Equal("Child", target.Self.Key); + Assert.Null(target.Self.Self); + + } + /*============================================================================================================================ | TEST: MAP: DISABLED PROPERTY: RETURNS NULL \---------------------------------------------------------------------------------------------------------------------------*/ From 4a67babe63ec02e319b9e4aefe99caa3b527ecec Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 4 Aug 2026 00:45:56 -0700 Subject: [PATCH 312/337] Added unit test for circular constructor reference This unit test utilizes the newly introduced `CircularConstructorTopicViewModel` (dbb47987) to create a scenario where a circular constructor reference occurs. This confirms that the circular constructor reference detection, including the completion semantics (7a5bd2c2, ee9a9a51, b197889e, 5a6b8a9a) and `MapPath` tracking (b42673a4, 61b1487c) as implemented in `resolveCachedEntry()` (1334a2bb). This contributes to testing of the `TopicMappingService`'s concurrency infrastructure (#118), and specifically around avoiding concurrent construction of new topic view models via the `MappedTopicCacheEntry`. --- OnTopic.Tests/TopicMappingServiceTest.cs | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/OnTopic.Tests/TopicMappingServiceTest.cs b/OnTopic.Tests/TopicMappingServiceTest.cs index 51f8d0dd..ea335b8f 100644 --- a/OnTopic.Tests/TopicMappingServiceTest.cs +++ b/OnTopic.Tests/TopicMappingServiceTest.cs @@ -496,6 +496,27 @@ public async Task Map_ConstructorRecord_ReturnsNewModel() { } + /*============================================================================================================================ + | TEST: MAP: CONSTRUCTOR (RECORD): THROWS EXCEPTION + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Establishes a and maps a positional record whose constructor references the + /// topic being mapped, and confirms that this circular constructor reference is detected and a is thrown. + /// + [Fact] + public async Task Map_ConstructorRecord_ThrowsException() { + + var topic = new Topic("Topic", "CircularConstructor", null, 1); + + topic.References.SetValue("Self", topic); + + await Assert.ThrowsAsync(async () => + await _mappingService.MapAsync(topic).ConfigureAwait(false) + ); + + } + /*============================================================================================================================ | TEST: MAP: DISABLED PROPERTY: RETURNS NULL \---------------------------------------------------------------------------------------------------------------------------*/ From 73e2f3ab891946201995241eb2bc41eb8afb971a Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 4 Aug 2026 01:11:13 -0700 Subject: [PATCH 313/337] Introduced models for concurrent mapping tests The `ConcurrentReferenceTopicViewModel` sets up two independent references to `SharedConcurrentTopicViewModel` view models, which will be mapped to the same topic, thus allowing us to evaluate that the same topic and can be mapped to the same view model within the same `MapAsync()` chain, so long as they're not in the same `MapPath` (b42673a4, 61b1487c), as detected via `resolveCacheEntry()` (1334a2bb). This will also evaluate the closely related completion semantics (7a5bd2c2, ee9a9a51, b197889e, 5a6b8a9a). This contributes to testing of the `TopicMappingService`'s concurrency infrastructure (#118), and specifically around allowing concurrent construction of new topic view models via the `MappedTopicCacheEntry`, so long as they're not in the same `MapPath`. --- .../TestDoubles/FakeViewModelLookupService.cs | 2 ++ .../ConcurrentReferenceTopicViewModel.cs | 36 +++++++++++++++++++ .../SharedConcurrentTopicViewModel.cs | 36 +++++++++++++++++++ 3 files changed, 74 insertions(+) create mode 100644 OnTopic.Tests/ViewModels/ConcurrentReferenceTopicViewModel.cs create mode 100644 OnTopic.Tests/ViewModels/SharedConcurrentTopicViewModel.cs diff --git a/OnTopic.Tests/TestDoubles/FakeViewModelLookupService.cs b/OnTopic.Tests/TestDoubles/FakeViewModelLookupService.cs index e7b7a791..9ee6b0c7 100644 --- a/OnTopic.Tests/TestDoubles/FakeViewModelLookupService.cs +++ b/OnTopic.Tests/TestDoubles/FakeViewModelLookupService.cs @@ -37,6 +37,7 @@ public FakeViewModelLookupService() { Add(typeof(AscendentTopicViewModel)); Add(typeof(CircularConstructorTopicViewModel)); Add(typeof(CircularTopicViewModel)); + Add(typeof(ConcurrentReferenceTopicViewModel)); Add(typeof(ConstructedTopicViewModel)); Add(typeof(DefaultValueTopicViewModel)); Add(typeof(DescendentSpecializedTopicViewModel)); @@ -61,6 +62,7 @@ public FakeViewModelLookupService() { Add(typeof(RelationWithChildrenTopicViewModel)); Add(typeof(RequiredObjectTopicViewModel)); Add(typeof(RequiredTopicViewModel)); + Add(typeof(SharedConcurrentTopicViewModel)); Add(typeof(TopicReferenceAttributeDescriptorTopicViewModel)); Add(typeof(TopicReferenceTopicViewModel)); diff --git a/OnTopic.Tests/ViewModels/ConcurrentReferenceTopicViewModel.cs b/OnTopic.Tests/ViewModels/ConcurrentReferenceTopicViewModel.cs new file mode 100644 index 00000000..8308cc70 --- /dev/null +++ b/OnTopic.Tests/ViewModels/ConcurrentReferenceTopicViewModel.cs @@ -0,0 +1,36 @@ +/*============================================================================================================================== +| Author Ignia, LLC +| Client Ignia, LLC +| Project Topics Library +\=============================================================================================================================*/ +using OnTopic.Mapping; + +namespace OnTopic.Tests.ViewModels; + +/*============================================================================================================================== +| VIEW MODEL: CONCURRENT REFERENCE TOPIC +\-----------------------------------------------------------------------------------------------------------------------------*/ +/// +/// Provides a strongly typed data transfer object with two topic references, both intended to resolve to the same shared . +/// +/// +/// +/// Both references are mapped as properties, so the resolves them concurrently within a +/// single mapping pass. When both point at the same topic, this drives two branches to map that topic to the same type at +/// once, which is a supported sibling concurrency scenario. The pins the mapped view model +/// type so the scenario does not depend on the shared topic's content type. +/// +/// +/// This is a sample class intended for test purposes only; it is not designed for use in a production environment. +/// +/// +public class ConcurrentReferenceTopicViewModel { + + [MapAs(typeof(SharedConcurrentTopicViewModel))] + public SharedConcurrentTopicViewModel? FirstReference { get; set; } + + [MapAs(typeof(SharedConcurrentTopicViewModel))] + public SharedConcurrentTopicViewModel? SecondReference { get; set; } + +} //Class \ No newline at end of file diff --git a/OnTopic.Tests/ViewModels/SharedConcurrentTopicViewModel.cs b/OnTopic.Tests/ViewModels/SharedConcurrentTopicViewModel.cs new file mode 100644 index 00000000..a51c84ed --- /dev/null +++ b/OnTopic.Tests/ViewModels/SharedConcurrentTopicViewModel.cs @@ -0,0 +1,36 @@ +/*============================================================================================================================== +| Author Ignia, LLC +| Client Ignia, LLC +| Project Topics Library +\=============================================================================================================================*/ +using OnTopic.Mapping; + +namespace OnTopic.Tests.ViewModels; + +/*============================================================================================================================== +| VIEW MODEL: SHARED CONCURRENT TOPIC +\-----------------------------------------------------------------------------------------------------------------------------*/ +/// +/// Provides a strongly typed data transfer object, implemented as a positional record, for testing that two concurrent +/// branches mapping the same topic to the same view model type share a single instance. +/// +/// +/// +/// The collection is mapped through a constructor parameter, so constructing this model requires the +/// source topic's payload to be loaded. When paired with a repository that suspends inside its lazy load, this lets a test +/// hold one branch mid-construction while a second branch reaches the same still-initializing cache entry, evaluating the +/// 's support of sibling concurrency. +/// +/// +/// The actual sibling references are set up in the accompanying . +/// +/// +/// This is a sample class intended for test purposes only; it is not designed for use in a production environment. +/// +/// +/// The key of the mapped topic. +/// A collection mapped from a constructor parameter, forcing the source payload to be loaded. +public record SharedConcurrentTopicViewModel( + string Key, + [Collection("Related")] Collection? Related +); \ No newline at end of file From 91d0a21636b00d69229e7d7bb9d50145fd2ad870 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 4 Aug 2026 01:12:36 -0700 Subject: [PATCH 314/337] Added `CreateGatedMappingService()` helper This introduces a new `CreateGatedMappingService()` helper method that constructs a new `BlockingStubLazyLoadingTopicRepository` so that the tests can recreate the exact concurrence scenario that the code confirms. This will be used in the testing of the `TopicMappingService`'s concurrency infrastructure (#118), and specifically around allowing concurrent construction of new topic view models via the `MappedTopicCacheEntry`, so long as they're not in the same `MapPath`. --- OnTopic.Tests/TopicMappingServiceTest.cs | 25 ++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/OnTopic.Tests/TopicMappingServiceTest.cs b/OnTopic.Tests/TopicMappingServiceTest.cs index ea335b8f..53614307 100644 --- a/OnTopic.Tests/TopicMappingServiceTest.cs +++ b/OnTopic.Tests/TopicMappingServiceTest.cs @@ -39,6 +39,7 @@ public class TopicMappingServiceTest { \---------------------------------------------------------------------------------------------------------------------------*/ readonly ITopicRepository _topicRepository; readonly ITopicMappingService _mappingService; + readonly ITypeLookupService _typeLookupService; /*============================================================================================================================ | CONSTRUCTOR @@ -64,6 +65,7 @@ public TopicMappingServiceTest(TopicInfrastructureFixture f \-------------------------------------------------------------------------------------------------------------------------*/ _topicRepository = fixture.CachedTopicRepository; _mappingService = fixture.MappingService; + _typeLookupService = fixture.TypeLookupService; } @@ -1996,4 +1998,27 @@ public async Task Map_CachedTopic_ReturnsUniqueReferencePerType() { public static TopicViewModel? GetChildTopic(IEnumerable? topicCollection, string key) => topicCollection?.FirstOrDefault((t) => t.Key.StartsWith(key, StringComparison.Ordinal)); + /*============================================================================================================================ + | METHOD: CREATE GATED MAPPING SERVICE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Assembles a fresh over a , + /// returning the service together with that gated repository and the wrapping it. + /// + /// + /// Each call returns a new, isolated set so concurrent-mapping tests can "arm", release, or fault their own gate without + /// interfering with one another. The stateless is reused, so + /// only the gated repository is constructed per test. + /// + /// The gated repository, the cache over it, and the mapping service. + private ( + BlockingStubLazyLoadingTopicRepository Repository, + CachedTopicRepository Cache, + ITopicMappingService MappingService + ) CreateGatedMappingService() { + var inner = new BlockingStubLazyLoadingTopicRepository(); + var cache = new CachedTopicRepository(inner); + return (inner, cache, new TopicMappingService(cache, _typeLookupService)); + } + } //Class \ No newline at end of file From 678bf643c71de56b71693d44ccb06dd8a8bf3f80 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 4 Aug 2026 01:14:50 -0700 Subject: [PATCH 315/337] Added unit test for concurrent model construction This test utilizes the new `ConcurrentReferenceTopicViewModel` and `SharedConcurrentTopicViewModel` view models (73e2f3ab) as well as the `CreateGatedMappingService()` helper (91d0a216) to evaluate that the same topic and can be mapped to the same view model within the same `MapAsync()` chain, so long as they're not in the same `MapPath` (b42673a4, 61b1487c), as detected via `resolveCacheEntry()` (1334a2bb). This also evaluate the closely related completion semantics (7a5bd2c2, ee9a9a51, b197889e, 5a6b8a9a). This contributes to testing of the `TopicMappingService`'s concurrency infrastructure (#118), and specifically around allowing concurrent construction of new topic view models via the `MappedTopicCacheEntry`, so long as they're not in the same `MapPath`. --- OnTopic.Tests/TopicMappingServiceTest.cs | 49 ++++++++++++++++++++++++ 1 file changed, 49 insertions(+) diff --git a/OnTopic.Tests/TopicMappingServiceTest.cs b/OnTopic.Tests/TopicMappingServiceTest.cs index 53614307..3be2d6db 100644 --- a/OnTopic.Tests/TopicMappingServiceTest.cs +++ b/OnTopic.Tests/TopicMappingServiceTest.cs @@ -519,6 +519,55 @@ await _mappingService.MapAsync(topic).Configu } + /*============================================================================================================================ + | TEST: MAP: CONCURRENT SIBLINGS: RETURNS SHARED INSTANCE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Confirms that two concurrent branches mapping the same topic to the same type within a single pass share one instance, + /// rather than the second branch mistaking the first's still-initializing entry for a circular constructor reference. + /// + /// + /// Uses , which suspends inside its own EnsureLoaded until + /// released, to hold the branch that wins construction of the shared model mid-constructor, guaranteeing the second branch + /// reaches the still-initializing entry and thus must await its completion. The shared topic is loaded through the + /// repository so it is stamped for lazy loading, and its constructor's collection parameter actually engages the gate; the + /// root is a plain whose in-memory references cannot trip the gate before the shared model is + /// constructed. Asserting the in-process task has not completed proves the first branch actually suspended, so the test + /// cannot pass without exercising the await path. + /// + [Fact] + public async Task Map_ConcurrentSiblings_ReturnsSharedInstance() { + + var (inner, cache, mappingService) = CreateGatedMappingService(); + + var shared = await cache.Load("Web"); + + Contract.Assume(shared); + + var root = new Topic("ConcurrentRoot", "Container", null, 5); + + root.References.SetValue("FirstReference", shared); + root.References.SetValue("SecondReference", shared); + + // "Arm" the gate so the branch that constructs the shared model suspends mid-constructor + inner.ArmEnsureLoadedGate(); + + var mapTask = mappingService.MapAsync(root); + + // Prove the first branch is genuinely suspended, so the second must await its completion + Assert.False(mapTask.IsCompleted); + + inner.ReleaseEnsureLoadedGate(); + + var result = await mapTask; + + Assert.NotNull(result); + Assert.NotNull(result.FirstReference); + Assert.NotNull(result.SecondReference); + Assert.Same(result.FirstReference, result.SecondReference); + + } + /*============================================================================================================================ | TEST: MAP: DISABLED PROPERTY: RETURNS NULL \---------------------------------------------------------------------------------------------------------------------------*/ From 6d590606f3c5026eb2dc2c968221c8d82e5b8a93 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 4 Aug 2026 01:20:39 -0700 Subject: [PATCH 316/337] Added unit test for faulty model construction This test utilizes the new `ConcurrentReferenceTopicViewModel` and `SharedConcurrentTopicViewModel` view models (73e2f3ab) as well as the `CreateGatedMappingService()` helper (91d0a216) to confirm that a `Fault()` that occurs during mapping, similar to what's implemented in `MapAsync()` (b197889e), throws an exception without hanging during concurrent construction of the same view model reference. This also relies on the broader completion semantics (7a5bd2c2, ee9a9a51, 5a6b8a9a) that are related to the `Fault()` concept. This contributes to testing of the `TopicMappingService`'s concurrency infrastructure (#118), and specifically around allowing concurrent construction of new topic view models via the `MappedTopicCacheEntry`, so long as they're not in the same `MapPath` and no exceptions are thrown (as evaluated in this test). --- OnTopic.Tests/TopicMappingServiceTest.cs | 40 ++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/OnTopic.Tests/TopicMappingServiceTest.cs b/OnTopic.Tests/TopicMappingServiceTest.cs index 3be2d6db..ab5ecbbe 100644 --- a/OnTopic.Tests/TopicMappingServiceTest.cs +++ b/OnTopic.Tests/TopicMappingServiceTest.cs @@ -568,6 +568,46 @@ public async Task Map_ConcurrentSiblings_ReturnsSharedInstance() { } + /*============================================================================================================================ + | TEST: MAP: CONCURRENT SIBLINGS: OBSERVES FAULT + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Confirms that when the branch constructing a shared model faults, a concurrent branch awaiting the same entry observes + /// the exception rather than hanging on a mapping that will never complete. + /// + /// + /// Uses the same setup as , but releases the gate with a fault so + /// the constructing branch throws while the second branch is awaiting the entry's completion. That the map throws, rather + /// than deadlocking, is what confirms the faulted entry releases its waiter. + /// + [Fact] + public async Task Map_ConcurrentSiblings_ObservesFault() { + + var (inner, cache, mappingService) = CreateGatedMappingService(); + + var shared = await cache.Load("Web"); + + Contract.Assume(shared); + + var root = new Topic("ConcurrentRoot", "Container", null, 5); + + root.References.SetValue("FirstReference", shared); + root.References.SetValue("SecondReference", shared); + + // "Arm" the gate so the branch that constructs the shared model suspends mid-constructor + inner.ArmEnsureLoadedGate(); + + var mapTask = mappingService.MapAsync(root); + + // Prove the first branch is genuinely suspended, so the second must await its completion + Assert.False(mapTask.IsCompleted); + + inner.FaultEnsureLoadedGate(new InvalidOperationException("Simulated load failure.")); + + await Assert.ThrowsAsync(async () => await mapTask.ConfigureAwait(false)); + + } + /*============================================================================================================================ | TEST: MAP: DISABLED PROPERTY: RETURNS NULL \---------------------------------------------------------------------------------------------------------------------------*/ From 86c6f7e6148e63c18f61fe758d12bc568f0184ee Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 4 Aug 2026 13:25:37 -0700 Subject: [PATCH 317/337] Lock creation of new view model collections When mapping a new view model via `SetCollectionValueAsync()`, lock the initialization of the collection object itself by the `topicId` (if available) and view model type to ensure that two concurrent mapping requests don't accidentally create two competing collections. This addresses one of the final concurrency issues with the `TopicMappingService` (#118). --- OnTopic/Mapping/TopicMappingService.cs | 25 +++++++++++++++++++++---- 1 file changed, 21 insertions(+), 4 deletions(-) diff --git a/OnTopic/Mapping/TopicMappingService.cs b/OnTopic/Mapping/TopicMappingService.cs index f14c333f..f468fc13 100644 --- a/OnTopic/Mapping/TopicMappingService.cs +++ b/OnTopic/Mapping/TopicMappingService.cs @@ -824,13 +824,30 @@ private async Task SetCollectionValueAsync( MapPath? mapPath = null ) { + /*-------------------------------------------------------------------------------------------------------------------------- + | Establish per-entry lock + >--------------------------------------------------------------------------------------------------------------------------- + | Two concurrent passes expanding the same cached target with disjoint associations (see e.g., the cache-hit path in + | MapAsync) can populate the same member's target list from different sources, so its creation and population are + | synchronized on the shared cache entry. A target that isn't cached (i.e., a new topic) is never shared across passes, so + | its own instance serves as a sufficient and uncontended lock. + \-------------------------------------------------------------------------------------------------------------------------*/ + cache.TryGetValue(source.Id, target.GetType(), out var cacheEntry); + var collectionLock = (object?)cacheEntry?? target; + /*-------------------------------------------------------------------------------------------------------------------------- | Ensure target list is created + >--------------------------------------------------------------------------------------------------------------------------- + | Locked so two concurrent passes can't both observe a null list and instantiate competing instances, which would orphan the + | items added to whichever collection is overwritten. The lock is synchronous and never held across an await. \-------------------------------------------------------------------------------------------------------------------------*/ - var targetList = (IList?)memberAccessor.GetValue(target); - if (targetList is null) { - targetList = InitializeCollection(memberAccessor.Type); - memberAccessor.SetValue(target, targetList); + IList? targetList; + lock (collectionLock) { + targetList = (IList?)memberAccessor.GetValue(target); + if (targetList is null) { + targetList = InitializeCollection(memberAccessor.Type); + memberAccessor.SetValue(target, targetList); + } } Contract.Assume( From 9dfc24c3e1f533d159ec1bcf26e96fe95f8f0636 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 4 Aug 2026 13:32:20 -0700 Subject: [PATCH 318/337] Lock the addition of view models to collections Using the same lock used to synchronize the creation of the collection itself (86c6f7e6), lock the addition of items to the collection via `PopulateTargetCollectionAsync()`, so that two concurrent additions don't conflict with one another. This addresses one of the last big items for `TopicMappingService` concurrency (#118). (That said, we'll still have smaller passes to go through after this.) --- OnTopic/Mapping/TopicMappingService.cs | 27 ++++++++++++++++++-------- 1 file changed, 19 insertions(+), 8 deletions(-) diff --git a/OnTopic/Mapping/TopicMappingService.cs b/OnTopic/Mapping/TopicMappingService.cs index f468fc13..aff17e3e 100644 --- a/OnTopic/Mapping/TopicMappingService.cs +++ b/OnTopic/Mapping/TopicMappingService.cs @@ -507,7 +507,7 @@ private async Task MapAsync( return null; } - await PopulateTargetCollectionAsync(sourceList, targetList, parameter, cache, mapPath).ConfigureAwait(false); + await PopulateTargetCollectionAsync(sourceList, targetList, parameter, cache, targetList, mapPath).ConfigureAwait(false); return targetList; @@ -869,7 +869,7 @@ private async Task SetCollectionValueAsync( /*-------------------------------------------------------------------------------------------------------------------------- | Map the topics from the source collection, and add them to the target collection \-------------------------------------------------------------------------------------------------------------------------*/ - await PopulateTargetCollectionAsync(sourceList, targetList, memberAccessor, cache, mapPath).ConfigureAwait(false); + await PopulateTargetCollectionAsync(sourceList, targetList, memberAccessor, cache, collectionLock, mapPath).ConfigureAwait(false); } @@ -1023,12 +1023,18 @@ IList getCollection(CollectionType collection, Func contain /// The target to add the mapped objects to. /// The with details about the property's attributes. /// A cache to keep track of already-mapped object instances. + /// + /// The object to lock on while adding to , so concurrent passes populating a shared target's + /// list from disjoint sources don't modify it simultaneously. Callers pass the shared cache entry for a cached target, or + /// the (unshared) list itself when populating a constructor parameter. + /// /// The current mapping request's path, used to detect circular references during construction. private async Task PopulateTargetCollectionAsync( IList sourceList, IList targetList, ItemMetadata itemMetadata, MappedTopicCache cache, + object collectionLock, MapPath? mapPath = null ) { @@ -1107,14 +1113,19 @@ configuration.ContentTypeFilter is not null && /*-------------------------------------------------------------------------------------------------------------------------- | Function: Add to List + >--------------------------------------------------------------------------------------------------------------------------- + | Locked so a concurrent pass populating the same shared list from a disjoint source can't add at the same time; the lock + | is synchronous and never held across an await, as child mapping happens outside of it via the above task queue. \-------------------------------------------------------------------------------------------------------------------------*/ void addToList(object dto) { - try { - targetList.Add(dto); - } - catch (ArgumentException) { - //Ignore exceptions caused by duplicate keys, in case the IList represents a keyed collection - //We would defensively check for this, except IList doesn't provide a suitable method to do so + lock (collectionLock) { + try { + targetList.Add(dto); + } + catch (ArgumentException) { + //Ignore exceptions caused by duplicate keys, in case the IList represents a keyed collection + //We would defensively check for this, except IList doesn't provide a suitable method to do so + } } } From a101412d72e6cd035ee2185e7cb58d15e9f085b3 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 4 Aug 2026 13:46:19 -0700 Subject: [PATCH 319/337] Allow the lazy concurrency repository fault This complements the existing `ArmEnsureLoadedGate()` and `ReleaseEnsureLoadedGate()` (2875725d, 8b56f3cd) with a new `FaultEnsureLoadedGate()`, which will allow us to simulate an exception as part of the testing of the mapped collection concurrently (86c6f7e6, 9dfc24c3) tests (#118). --- .../BlockingStubLazyLoadingTopicRepository.cs | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/OnTopic.Tests/TestDoubles/BlockingStubLazyLoadingTopicRepository.cs b/OnTopic.Tests/TestDoubles/BlockingStubLazyLoadingTopicRepository.cs index d3f0ef7e..d8aca6ca 100644 --- a/OnTopic.Tests/TestDoubles/BlockingStubLazyLoadingTopicRepository.cs +++ b/OnTopic.Tests/TestDoubles/BlockingStubLazyLoadingTopicRepository.cs @@ -76,6 +76,16 @@ internal sealed class BlockingStubLazyLoadingTopicRepository: StubLazyLoadingTop /// public void ReleaseEnsureLoadedGate() => _ensureLoadedGate?.SetResult(); + /*============================================================================================================================ + | METHOD: FAULT ENSURE LOADED GATE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Faults a suspended call "armed" via with the supplied + /// , so a test can simulate a lazy load that throws while a second pass awaits the same entry. + /// + /// The exception to surface from the suspended call. + public void FaultEnsureLoadedGate(Exception exception) => _ensureLoadedGate?.SetException(exception); + /*============================================================================================================================ | METHOD: LOAD \---------------------------------------------------------------------------------------------------------------------------*/ From 96eae010fa1b05fec66d73cfd8d94d96cb3985b2 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 4 Aug 2026 13:49:05 -0700 Subject: [PATCH 320/337] Introduced models for collection concurrency tests These two view models setup the conditions that will allow us to test the locks on `SetCollectionValueAsync()` (86c6f7e6), which prevents duplicate collections from being created, and `PopulateTargetCollectionAsync()` (9dfc24c3), which prevents two items from being added concurrently. This contributes to the testing of the `TopicMappingService` concurrency (#118). --- .../TestDoubles/FakeViewModelLookupService.cs | 2 + .../ConcurrentExpansionRootTopicViewModel.cs | 36 ++++++++++++++++ ...ConcurrentExpansionSharedTopicViewModel.cs | 41 +++++++++++++++++++ 3 files changed, 79 insertions(+) create mode 100644 OnTopic.Tests/ViewModels/ConcurrentExpansionRootTopicViewModel.cs create mode 100644 OnTopic.Tests/ViewModels/ConcurrentExpansionSharedTopicViewModel.cs diff --git a/OnTopic.Tests/TestDoubles/FakeViewModelLookupService.cs b/OnTopic.Tests/TestDoubles/FakeViewModelLookupService.cs index 9ee6b0c7..04f2ccde 100644 --- a/OnTopic.Tests/TestDoubles/FakeViewModelLookupService.cs +++ b/OnTopic.Tests/TestDoubles/FakeViewModelLookupService.cs @@ -37,6 +37,8 @@ public FakeViewModelLookupService() { Add(typeof(AscendentTopicViewModel)); Add(typeof(CircularConstructorTopicViewModel)); Add(typeof(CircularTopicViewModel)); + Add(typeof(ConcurrentExpansionRootTopicViewModel)); + Add(typeof(ConcurrentExpansionSharedTopicViewModel)); Add(typeof(ConcurrentReferenceTopicViewModel)); Add(typeof(ConstructedTopicViewModel)); Add(typeof(DefaultValueTopicViewModel)); diff --git a/OnTopic.Tests/ViewModels/ConcurrentExpansionRootTopicViewModel.cs b/OnTopic.Tests/ViewModels/ConcurrentExpansionRootTopicViewModel.cs new file mode 100644 index 00000000..55d1c093 --- /dev/null +++ b/OnTopic.Tests/ViewModels/ConcurrentExpansionRootTopicViewModel.cs @@ -0,0 +1,36 @@ +/*============================================================================================================================== +| Author Ignia, LLC +| Client Ignia, LLC +| Project Topics Library +\=============================================================================================================================*/ + +namespace OnTopic.Tests.ViewModels; + +/*============================================================================================================================== +| VIEW MODEL: CONCURRENT EXPANSION ROOT +\-----------------------------------------------------------------------------------------------------------------------------*/ +/// +/// Provides a parent view model that references the same source topic twice with disjoint associations, forcing two +/// concurrent mapping passes over the shared target. +/// +/// +/// +/// Both and resolve to the same source topic, but request +/// disjoint associations via . Because both reference properties are mapped concurrently (via +/// the property-level Task.WhenAll), one pass constructs the shared instance while the other expands it, each +/// populating the target's list from a different source; this +/// is the scenario that the SetCollectionValueAsync() and PopulateTargetCollectionAsync() locks protect against. +/// +/// +/// This is a sample class intended for test purposes only; it is not designed for use in a production environment. +/// +/// +public class ConcurrentExpansionRootTopicViewModel { + + [Include(AssociationTypes.Relationships)] + public ConcurrentExpansionSharedTopicViewModel? RelationshipsView { get; set; } + + [Include(AssociationTypes.IncomingRelationships)] + public ConcurrentExpansionSharedTopicViewModel? IncomingView { get; set; } + +} //Class \ No newline at end of file diff --git a/OnTopic.Tests/ViewModels/ConcurrentExpansionSharedTopicViewModel.cs b/OnTopic.Tests/ViewModels/ConcurrentExpansionSharedTopicViewModel.cs new file mode 100644 index 00000000..b14393d5 --- /dev/null +++ b/OnTopic.Tests/ViewModels/ConcurrentExpansionSharedTopicViewModel.cs @@ -0,0 +1,41 @@ +/*============================================================================================================================== +| Author Ignia, LLC +| Client Ignia, LLC +| Project Topics Library +\=============================================================================================================================*/ + +namespace OnTopic.Tests.ViewModels; + +/*============================================================================================================================== +| VIEW MODEL: CONCURRENT EXPANSION SHARED +\-----------------------------------------------------------------------------------------------------------------------------*/ +/// +/// Provides a shared target for two concurrent mapping passes with disjoint associations, exposing a single collection () populated from two different sources. +/// +/// +/// +/// This is the referenced view model in the concurrency stress test: A single source topic is referenced twice from a +/// parent , once with and +/// once with . Both passes populate the same +/// list: One from the source's outgoing relationships, the other from its incoming relationships, thus exercising the locks +/// on SetCollectionValueAsyn() and PopulateTargetCollectionAsync(). The property is left nullable and settable so the +/// mapper both creates the backing list (SetCollectionValueAsyn()) and adds to it (PopulateTargetCollectionAsync()). +/// +/// +/// This is a sample class intended for test purposes only; it is not designed for use in a production environment. +/// +/// +[SuppressMessage( + "Usage", + "CA2227:Collection properties should be read only", + Justification = "This view model intentionally exposes a settable, nullable collection property so the TopicMappingService's list-creation runs, which the concurrency test relies on to establish a creation race." +)] +public class ConcurrentExpansionSharedTopicViewModel { + + public string? Key { get; set; } + + [Collection("Related")] + public Collection? Related { get; set; } + +} //Class \ No newline at end of file From f6a85a24bc5abe989d884e2236cf89ac1e8af45a Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 4 Aug 2026 14:40:19 -0700 Subject: [PATCH 321/337] Introduced new `RendezvousTopicLazyLoader` The `RendezvousTopicLazyLoader` allows us to test the locks on `SetCollectionValueAsync()` (86c6f7e6), which prevents duplicate collections from being created, and `PopulateTargetCollectionAsync()` (9dfc24c3), which prevents two items from being added concurrently. Unlike all other `ITopicLazyLoader` implementations, this is _purely_ a lazy loader; it is not bundled with an actual `ITopicRepository`, nor does it rely on e.g., `Load()` or any other integration with a persistence store to serve its narrow testing purpose. This contributes to the testing of the `TopicMappingService` concurrency (#118). --- .../TestDoubles/RendezvousTopicLazyLoader.cs | 139 ++++++++++++++++++ 1 file changed, 139 insertions(+) create mode 100644 OnTopic.Tests/TestDoubles/RendezvousTopicLazyLoader.cs diff --git a/OnTopic.Tests/TestDoubles/RendezvousTopicLazyLoader.cs b/OnTopic.Tests/TestDoubles/RendezvousTopicLazyLoader.cs new file mode 100644 index 00000000..08c6fd1e --- /dev/null +++ b/OnTopic.Tests/TestDoubles/RendezvousTopicLazyLoader.cs @@ -0,0 +1,139 @@ +/*============================================================================================================================== +| Author Ignia, LLC +| Client Ignia, LLC +| Project Topics Library +\=============================================================================================================================*/ +using OnTopic.Repositories; + +namespace OnTopic.Tests.TestDoubles; + +/*============================================================================================================================== +| CLASS: RENDEZVOUS TOPIC LAZY LOADER +\-----------------------------------------------------------------------------------------------------------------------------*/ +/// +/// An that suspends each call until a fixed number +/// of concurrent passes have arrived, then releases them together, so a stress test can force two concurrent mapping passes +/// to modify a shared collection at the same time without timing hacks. Conceptually, this is an asynchronous, cyclic for a fixed number of mapping passes. +/// +/// +/// +/// Unlike a repository-backed lazy loader, this performs no fetching: The stress test wires the shared topic's associations +/// before mapping, so only needs to a) "rendezvous" the concurrent passes and +/// b) mark as so the base pass's nested-topic search, which +/// reads the autoloading getter, doesn't re-enter this loader. The rendezvous rearms after +/// each release, so a single instance serves every repetition. +/// +/// +/// This is a sample class intended for test purposes only; it is not designed for use in a production environment. +/// +/// +[ExcludeFromCodeCoverage] +internal sealed class RendezvousTopicLazyLoader: ITopicLazyLoader { + + /*============================================================================================================================ + | PRIVATE FIELDS + \---------------------------------------------------------------------------------------------------------------------------*/ + private readonly object _lock = new(); + private readonly int _participantCount; + private readonly TimeSpan _timeout; + private TaskCompletionSource _gate = new(TaskCreationOptions.RunContinuationsAsynchronously); + private int _arrivals; + + /*============================================================================================================================ + | CONSTRUCTOR + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Instantiates a new instance of the that releases once passes have arrived. + /// + /// The number of concurrent passes to await before releasing them together. + /// + /// The number of seconds an arrived pass waits for the others before throwing, guarding against a hang if the expected + /// concurrency never materializes. + /// + public RendezvousTopicLazyLoader(int participantCount = 2, int timeoutSeconds = 10) { + _participantCount = participantCount; + _timeout = TimeSpan.FromSeconds(timeoutSeconds); + } + + /*============================================================================================================================ + | METHOD: ENSURE LOADED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + async Task ITopicLazyLoader.EnsureLoaded(Topic topic, TopicPayload payload, CancellationToken cancellationToken) { + + // Suspend until the concurrent passes rendezvous, so they resume together and race on the shared collection + await Rendezvous(cancellationToken).ConfigureAwait(false); + + // Mark children Loaded so the base pass's nested-topic probe, which reads the autoloading Topic.Children getter, doesn't + // re-enter this loader. Relationships needs no such treatment: Its targets are preloaded, so its (derived) LoadState is + // already Loaded and so relationship never autoload. + ((ITopicBackingAccessor)topic).Children.LoadState = LoadState.Loaded; + + } + + /*============================================================================================================================ + | METHOD: RENDEZVOUS + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Suspends the caller until passes have arrived, then releases them together and re-arms + /// for the next batch. + /// + /// A token used to cancel the wait. + private Task Rendezvous(CancellationToken cancellationToken) { + + /*-------------------------------------------------------------------------------------------------------------------------- + | Register arrival and, if last, re-arm the gate for the next batch + \-------------------------------------------------------------------------------------------------------------------------*/ + TaskCompletionSource gate; + bool release; + lock (_lock) { + gate = _gate; + release = ++_arrivals >= _participantCount; + if (release) { + _arrivals = 0; + _gate = new(TaskCreationOptions.RunContinuationsAsynchronously); + } + } + + /*-------------------------------------------------------------------------------------------------------------------------- + | The last arrival releases the batch and proceeds without waiting + \-------------------------------------------------------------------------------------------------------------------------*/ + if (release) { + gate.TrySetResult(); + return Task.CompletedTask; + } + + /*-------------------------------------------------------------------------------------------------------------------------- + | Earlier arrivals wait for the last, throwing on timeout so a broken assumption fails loudly instead of hanging + \-------------------------------------------------------------------------------------------------------------------------*/ + return AwaitGate(gate, cancellationToken); + + } + + /*============================================================================================================================ + | METHOD: AWAIT GATE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Waits for to be released, throwing a if the batch never + /// completes. + /// + /// The gate to wait on for the current batch. + /// A token used to cancel the wait. + private async Task AwaitGate(TaskCompletionSource gate, CancellationToken cancellationToken) { + + // Race the gate against a timeout, so an unexpected participant count can't hang the test suite + var completed = await Task.WhenAny(gate.Task, Task.Delay(_timeout, cancellationToken)).ConfigureAwait(false); + + // Surface a failed rendezvous as an exception rather than proceeding with a corrupt result + if (completed != gate.Task) { + throw new TimeoutException( + $"The rendezvous timed out after {_timeout.TotalSeconds:0} seconds waiting for {_participantCount} concurrent " + + $"passes; the expected concurrency did not occur." + ); + } + + } + +} //Class \ No newline at end of file From 3a50d6b9ca5916c2e6c2c33330af28803c18db21 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 4 Aug 2026 15:00:21 -0700 Subject: [PATCH 322/337] Added unit tests for concurrent collection mapping The `RendezvousTopicLazyLoader` allows us to test the locks on `SetCollectionValueAsync()` (86c6f7e6), which prevents duplicate collections from being created, and `PopulateTargetCollectionAsync()` (9dfc24c3), which prevents two items from being added concurrently. This relies on the `RendezvousTopicLazyLoader` (f6a85a24), the `ConcurrentExpansion` topic view models (96eae010), and the new `FaultEnsureLoadedGate()` (a101412d). It also introduces a new `BuildConcurrentExpansionGraph()` helper to construct the graph itself. This contributes to the testing of the mapped collection concurrently (86c6f7e6, 9dfc24c3) tests (#118). --- OnTopic.Tests/TopicMappingServiceTest.cs | 123 ++++++++++++++++++++++- 1 file changed, 121 insertions(+), 2 deletions(-) diff --git a/OnTopic.Tests/TopicMappingServiceTest.cs b/OnTopic.Tests/TopicMappingServiceTest.cs index ab5ecbbe..8809978c 100644 --- a/OnTopic.Tests/TopicMappingServiceTest.cs +++ b/OnTopic.Tests/TopicMappingServiceTest.cs @@ -608,6 +608,57 @@ public async Task Map_ConcurrentSiblings_ObservesFault() { } + /*============================================================================================================================ + | TEST: MAP: CONCURRENT SHARED COLLECTION: POPULATES DETERMINISTICALLY + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Stress test confirming that two concurrent passes expanding the same shared model with disjoint associations, each + /// populating the same collection from a different source, deterministically produce the union of both sources without + /// corrupting the shared list. + /// + /// + /// A parent references one shared topic twice, with disjoint sets ( and ). Whichever pass wins + /// construction populates the shared list from one source; + /// the other expands it from the other, so the result should always be the union of both, regardless of which pass wins. A + /// holds the two passes at the collection warm-up until both arrive, then releases + /// them together, so their list mutations genuinely overlap. Repeated many times to give the race a chance to manifest; + /// without the shared-list mutation guard, the concurrent adds corrupt the list, dropping items or throwing. + /// + [Fact] + public async Task Map_ConcurrentSharedCollection_PopulatesDeterministically() { + + const int relationshipCount = 12; + const int incomingCount = 12; + const int repetitions = 100; + + var loader = new RendezvousTopicLazyLoader(participantCount: 2); + + for (var repetition = 0; repetition < repetitions; repetition++) { + + var root = BuildConcurrentExpansionGraph(loader, relationshipCount, incomingCount, out var shared); + + // Guard against an incomplete setup: Both sources must be loaded before mapping; read them via the backing accessor so + // the precondition check doesn't itself trip the loader's rendezvous and hang + var backing = (ITopicBackingAccessor)shared; + Assert.Equal(relationshipCount, backing.Relationships.GetValues("Related").Count); + Assert.Equal(incomingCount, shared.IncomingRelationships.GetValues("Related").Count); + + var result = await _mappingService.MapAsync(root); + + Assert.NotNull(result); + Assert.NotNull(result.RelationshipsView); + Assert.NotNull(result.IncomingView); + + // Both references resolve to the one shared instance, whose list holds the union of both sources + Assert.Same(result.RelationshipsView, result.IncomingView); + Assert.NotNull(result.RelationshipsView.Related); + Assert.Equal(relationshipCount + incomingCount, result.RelationshipsView.Related.Count); + + } + + } + /*============================================================================================================================ | TEST: MAP: DISABLED PROPERTY: RETURNS NULL \---------------------------------------------------------------------------------------------------------------------------*/ @@ -776,7 +827,7 @@ public async Task Map_AlternateAttributeKey_ReturnsMappedModel() { \---------------------------------------------------------------------------------------------------------------------------*/ /// /// Establishes a and then confirms that it is returned via . + /// "MappedTopicCache.TryGetValue"/>. /// [Fact] public void MappedTopicCache_TryGetValue_ReturnsEntry() { @@ -799,7 +850,7 @@ public void MappedTopicCache_TryGetValue_ReturnsEntry() { \---------------------------------------------------------------------------------------------------------------------------*/ /// /// Establishes a and then confirms that it is not returned via if the doesn't match. + /// .TryGetValue"/> if the doesn't match. /// [Fact] public void MappedTopicCache_TryGetValue_ReturnsNull() { @@ -2110,4 +2161,72 @@ ITopicMappingService MappingService return (inner, cache, new TopicMappingService(cache, _typeLookupService)); } + /*============================================================================================================================ + | METHOD: BUILD CONCURRENT EXPANSION GRAPH + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Builds an in-memory graph for : A parent that + /// references a single topic twice, that topic having + /// outgoing relationships and incoming relationships under the key Related. + /// + /// + /// Everything is preloaded, so performs no fetching; only the topic is + /// stamped for lazy loading, since only its EnsureLoaded needs to "rendezvous" the two passes. Its is left so the mapper's collection warm-up actually calls + /// the loader, which then marks it before the base pass's nested-topic probe reads it. The + /// relationships are already . The shared topic deliberately has no Related child, so + /// the nested-topic probe never displaces the relationship and incoming-relationship sources. + /// + /// The lazy loader to stamp on the shared topic. + /// The number of outgoing relationships to wire under Related. + /// The number of incoming relationships to wire under Related. + /// The shared topic referenced twice by the returned parent. + /// The parent topic to map. + private static Topic BuildConcurrentExpansionGraph( + ITopicLazyLoader loader, + int relationshipCount, + int incomingCount, + out Topic shared + ) { + + /*-------------------------------------------------------------------------------------------------------------------------- + | Establish the parent and the shared target + \-------------------------------------------------------------------------------------------------------------------------*/ + var identity = 1; + var root = new Topic("ConcurrentExpansionRoot", "ConcurrentExpansionRoot", null, identity++); + shared = new Topic("Shared", "ConcurrentExpansionShared", null, identity++); + var backing = (ITopicBackingAccessor)shared; + + /*-------------------------------------------------------------------------------------------------------------------------- + | Wire the shared target's outgoing relationships (the first source for the shared collection) + \-------------------------------------------------------------------------------------------------------------------------*/ + for (var index = 0; index < relationshipCount; index++) { + backing.Relationships.SetValue("Related", new($"Relationship_{index}", "KeyOnly", null, identity++)); + } + + /*-------------------------------------------------------------------------------------------------------------------------- + | Wire the shared target's incoming relationships (the second source), via each origin's reciprocal outgoing relationship + \-------------------------------------------------------------------------------------------------------------------------*/ + for (var index = 0; index < incomingCount; index++) { + var origin = new Topic($"Incoming_{index}", "KeyOnly", null, identity++); + origin.Relationships.SetValue("Related", shared); + } + + /*-------------------------------------------------------------------------------------------------------------------------- + | Stamp the shared target and leave children NotLoaded so the collection warm-up calls the loader exactly once per pass; the + | relationships are already Loaded (no deferred targets), so the relationship probe reads them without autoloading + \-------------------------------------------------------------------------------------------------------------------------*/ + ((ITopicLazyLoadable)shared).Loader = loader; + backing.Children.LoadState = LoadState.NotLoaded; + + /*-------------------------------------------------------------------------------------------------------------------------- + | Reference the shared target twice from the parent, so both references map it concurrently + \-------------------------------------------------------------------------------------------------------------------------*/ + root.References.SetValue("RelationshipsView", shared); + root.References.SetValue("IncomingView", shared); + + return root; + + } + } //Class \ No newline at end of file From c5f191b6062dad15733b3f1e5ae0f14f81e51209 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 4 Aug 2026 15:28:31 -0700 Subject: [PATCH 323/337] Rely on `WhenAll()` over `WhenAny()` This ensures that the order of siblings is honored. This wasn't an issue prior to lazy loading (#111) since tasks were CPU bound, but with the possibility of some siblings being fully loaded while others need to `await` a call to the persistence store, it's very easy for this to occur. This contributes to the concurrency fixes for `TopicMappingService` (#118). --- OnTopic/Mapping/TopicMappingService.cs | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/OnTopic/Mapping/TopicMappingService.cs b/OnTopic/Mapping/TopicMappingService.cs index aff17e3e..a2e76169 100644 --- a/OnTopic/Mapping/TopicMappingService.cs +++ b/OnTopic/Mapping/TopicMappingService.cs @@ -1101,11 +1101,13 @@ configuration.ContentTypeFilter is not null && /*-------------------------------------------------------------------------------------------------------------------------- | Process mapping tasks + >--------------------------------------------------------------------------------------------------------------------------- + | Awaited as a batch, then added in the order the tasks were queued in, rather than completion order; this keeps sibling + | order deterministic regardless of which child mappings genuinely await \-------------------------------------------------------------------------------------------------------------------------*/ - while (taskQueue.Count > 0) { - var dtoTask = await Task.WhenAny(taskQueue).ConfigureAwait(false); - var dto = await dtoTask.ConfigureAwait(false); - taskQueue.Remove(dtoTask); + var dtos = await Task.WhenAll(taskQueue).ConfigureAwait(false); + + foreach (var dto in dtos) { if (dto is not null) { addToList(dto); } From 3359853e73559b855f8677e8bd153793ed0bc09d Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 4 Aug 2026 15:36:18 -0700 Subject: [PATCH 324/337] Introduced `StaggeredTopicLazyLoader` This provides a new `ITopicLazyLoader` test double which allows a `delay` to be registered as part of its construction, which is executed as part of `EnsureLoaded()`. This allows multiple calls to different instances of the loader to set different delays and, thus, result in out-of-order resolution of siblings, thus providing a test harness for the new `WhenAll()` fix (c5f191b6). This contributes to the testing of the `ITopicMappingService` concurrency (#118). --- .../TestDoubles/StaggeredTopicLazyLoader.cs | 35 +++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 OnTopic.Tests/TestDoubles/StaggeredTopicLazyLoader.cs diff --git a/OnTopic.Tests/TestDoubles/StaggeredTopicLazyLoader.cs b/OnTopic.Tests/TestDoubles/StaggeredTopicLazyLoader.cs new file mode 100644 index 00000000..964735e9 --- /dev/null +++ b/OnTopic.Tests/TestDoubles/StaggeredTopicLazyLoader.cs @@ -0,0 +1,35 @@ +/*============================================================================================================================== +| Author Ignia, LLC +| Client Ignia, LLC +| Project Topics Library +\=============================================================================================================================*/ +using OnTopic.Repositories; + +namespace OnTopic.Tests.TestDoubles; + +/*============================================================================================================================== +| CLASS: STAGGERED TOPIC LAZY LOADER +\-----------------------------------------------------------------------------------------------------------------------------*/ +/// +/// An that suspends for a fixed before completing, so a test can attach different instances to sibling topics and force their loads to +/// genuinely complete out of source order. +/// +/// +/// This is a sample class intended for test purposes only; it is not designed for use in a production environment. +/// +[ExcludeFromCodeCoverage] +internal sealed class StaggeredTopicLazyLoader(TimeSpan delay): ITopicLazyLoader { + + /*============================================================================================================================ + | METHOD: ENSURE LOADED + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + async Task ITopicLazyLoader.EnsureLoaded(Topic topic, TopicPayload payload, CancellationToken cancellationToken) { + if (delay > TimeSpan.Zero) { + await Task.Delay(delay, cancellationToken).ConfigureAwait(false); + } + ((ITopicBackingAccessor)topic).Children.LoadState = LoadState.Loaded; + } + +} //Class \ No newline at end of file From 1a631ab344a8a685a521ffea286a5cb24555ff3b Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 4 Aug 2026 15:40:56 -0700 Subject: [PATCH 325/337] Added unit test for collection mapping order This utilizes the newly introduced `StaggeredTopicLazyLoader` (3359853e) to validate the `WhenAll()` fix (c5f191b6) for ensuring source order is maintained when mapping collections. This contributes to the concurrency fixes for `TopicMappingService` (#118). --- OnTopic.Tests/TopicMappingServiceTest.cs | 36 ++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/OnTopic.Tests/TopicMappingServiceTest.cs b/OnTopic.Tests/TopicMappingServiceTest.cs index 8809978c..b44fc322 100644 --- a/OnTopic.Tests/TopicMappingServiceTest.cs +++ b/OnTopic.Tests/TopicMappingServiceTest.cs @@ -1272,6 +1272,42 @@ public async Task Map_Children_ReturnsMappedModel() { )); } + /*============================================================================================================================ + | TEST: MAP: CHILDREN: STAGGERED COMPLETION: PRESERVES SOURCE ORDER + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Establishes a with children whose mapping tasks are forced to complete in reverse of + /// source order, and tests that the mapped collection nonetheless preserves source order. + /// + /// + /// Each child is stamped with its own and left + /// for , so mapping it genuinely awaits a delay before completing. The first child gets + /// the longest delay and the last gets none, so completion order is the reverse of source order; if collection population + /// added results in completion order rather than source order, this would come back reversed. + /// + [Fact] + public async Task Map_Children_StaggeredCompletion_PreservesSourceOrder() { + + var topic = new Topic("Test", "Descendent"); + var childKeys = new[] { "ChildTopic1", "ChildTopic2", "ChildTopic3", "ChildTopic4" }; + + for (var index = 0; index < childKeys.Length; index++) { + var child = new Topic(childKeys[index], "Descendent", topic); + var delay = TimeSpan.FromMilliseconds((childKeys.Length - index) * 25); + ((ITopicLazyLoadable)child).Loader = new StaggeredTopicLazyLoader(delay); + ((ITopicBackingAccessor)child).Children.LoadState = LoadState.NotLoaded; + } + + var target = await _mappingService.MapAsync(topic); + + Assert.NotNull(target); + Assert.Equal(childKeys.Length, target.Children.Count); + for (var index = 0; index < childKeys.Length; index++) { + Assert.Equal(childKeys[index], target.Children[index].Key); + } + + } + /*============================================================================================================================ | TEST: MAP: WITH DISABLED: SKIPS DISABLED \---------------------------------------------------------------------------------------------------------------------------*/ From 487ecf2d1001c94151dfa052e992fa5cfef261ea Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 4 Aug 2026 15:42:20 -0700 Subject: [PATCH 326/337] Prefer direct `WhenAll(IEnumerable)` Previously, the queue was being wrapped in another array unnecessarily. --- OnTopic/Mapping/TopicMappingService.cs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/OnTopic/Mapping/TopicMappingService.cs b/OnTopic/Mapping/TopicMappingService.cs index a2e76169..4ae26e71 100644 --- a/OnTopic/Mapping/TopicMappingService.cs +++ b/OnTopic/Mapping/TopicMappingService.cs @@ -292,7 +292,7 @@ public class TopicMappingService(ITopicRepository topicRepository, ITypeLookupSe } } - await Task.WhenAll([.. propertyQueue]).ConfigureAwait(false); + await Task.WhenAll(propertyQueue).ConfigureAwait(false); /*-------------------------------------------------------------------------------------------------------------------------- | Return target @@ -427,7 +427,7 @@ private async Task MapAsync( foreach (var property in typeAccessor.GetMembers(MemberTypes.Property)) { taskQueue.Add(SetPropertyAsync(topic, target, associations, property, cache, attributePrefix, cacheEntry is not null, mapPath)); } - await Task.WhenAll([.. taskQueue]).ConfigureAwait(false); + await Task.WhenAll(taskQueue).ConfigureAwait(false); /*-------------------------------------------------------------------------------------------------------------------------- | Return result From 3a168365073cddc86d5d0a480b05c01ac810303f Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 4 Aug 2026 16:02:49 -0700 Subject: [PATCH 327/337] Cover `Deferred` in `Topic.Relationships.Clear()` This updates the `Clear()` method on the `TopicRelationshipMultiMap()` to not only include the `Deferred` collection, but also to mark the collection as dirty if only deferred items were cleared. Unlike the rest of this branch, this doesn't pertain to concurrency issues created by lazy loading (#111), but it does relate to a bug exposed in the `ReverseTopicMappingService` by the introduction of the `Deferred` associations. --- .../Associations/TopicRelationshipMultiMap.cs | 25 +++++++++++++++---- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/OnTopic/Associations/TopicRelationshipMultiMap.cs b/OnTopic/Associations/TopicRelationshipMultiMap.cs index 94021454..dfcdafa1 100644 --- a/OnTopic/Associations/TopicRelationshipMultiMap.cs +++ b/OnTopic/Associations/TopicRelationshipMultiMap.cs @@ -67,20 +67,35 @@ internal void Clear() { } /// - /// Removes all objects grouped by a specific . + /// Removes all objects grouped by a specific , as well as any entries registered under that key. /// /// - /// If there are any objects in the specified , then the will be marked as . Delegates to for each entry so the reciprocal relationship is also removed from each target's . + /// If there are any objects or entries registered under the specified , then the will be marked as . Delegates to for each resolved entry so the + /// reciprocal relationship is also removed from each target's . Clearing the entries prevents a subsequent from resolving and + /// resurrecting relationships this call just removed. /// /// The key of the relationship to be cleared. public void Clear(string relationshipKey) { + Contract.Requires(!String.IsNullOrWhiteSpace(relationshipKey), nameof(relationshipKey)); + + var hadLoadedValues = _storage.GetValues(relationshipKey).Count > 0; + var hadDeferredEntries = Deferred.Remove(relationshipKey); + foreach (var topic in _storage.GetValues(relationshipKey).ToArray()) { Remove(relationshipKey, topic); } + + // Remove() already marks the key dirty for each resident topic it removes; if only deferred entries existed, mark it here + // so the clear isn't silently lost + if (!hadLoadedValues && hadDeferredEntries) { + _dirtyKeys.MarkAs(relationshipKey, markDirty: !_parent.IsNew); + } + } /// From e308bc5bfee26692e966b446c3cb605792adf029 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 4 Aug 2026 16:10:02 -0700 Subject: [PATCH 328/337] Added unit test to confirm `Clear()` fix This confirms that the `Topic.Relationships.Clear()` call successfully removes `Deferred` items as well as resolved items, as per the recent fix (3a168365). Unlike the rest of this branch, this doesn't pertain to concurrency issues created by lazy loading (#111), but it does relate to a bug exposed in the `ReverseTopicMappingService` by the introduction of the `Deferred` associations. --- .../TopicRelationshipMultiMapTest.cs | 24 +++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/OnTopic.Tests/TopicRelationshipMultiMapTest.cs b/OnTopic.Tests/TopicRelationshipMultiMapTest.cs index bc563d74..4b5604e5 100644 --- a/OnTopic.Tests/TopicRelationshipMultiMapTest.cs +++ b/OnTopic.Tests/TopicRelationshipMultiMapTest.cs @@ -491,6 +491,30 @@ public void Clear_NoTopics_IsNotDirty() { } + /*============================================================================================================================ + | TEST: CLEAR: DEFERRED ENTRIES: REMOVES DEFERRED ENTRIES AND IS DIRTY + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Registers a entry with no corresponding target and + /// calls , confirming that the deferred entry is purged and reports true, even though no target topic was removed. + /// + [Fact] + public void Clear_DeferredEntries_RemovesDeferredEntriesAndIsDirty() { + + var topic = new Topic("Test", "Page", null, 1); + var relationships = new TopicRelationshipMultiMap(topic); + + relationships.Deferred.SetValue("Related", 999); + relationships.Deferred.SetValue("Other", 998); + relationships.Clear("Related"); + + Assert.False(relationships.Deferred.Remove("Related")); + Assert.True(relationships.Deferred.Remove("Other")); + Assert.True(relationships.IsDirty()); + + } + /*============================================================================================================================ | TEST: SET VALUE: MARK NOT DIRTY: IS NOT DIRTY \---------------------------------------------------------------------------------------------------------------------------*/ From 7d5cad06ee3ece3574ff1e33dedfaf12cfbebfee Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 4 Aug 2026 16:18:11 -0700 Subject: [PATCH 329/337] Added unit test to test context of `Clear()` fix In the previous unit test (e308bc5b), I validated the base `Clear()` fix, ensuring that `Deferred` items are cleared alongside resolved targets (3a168365). This test complements that by ensuring that fix prevents `EnsureLoaded()` from "resurrecting" the deferred items after a `Clear()`, which is the core bug that the `ReverseTopicMappingService` was running into. Unlike the rest of this branch, this doesn't pertain to concurrency issues created by lazy loading (#111), but it does relate to a bug exposed in the `ReverseTopicMappingService` by the introduction of the `Deferred` associations (#118). --- OnTopic.Tests/ITopicLazyLoadableTest.cs | 40 ++++++++++++++++++++++++- 1 file changed, 39 insertions(+), 1 deletion(-) diff --git a/OnTopic.Tests/ITopicLazyLoadableTest.cs b/OnTopic.Tests/ITopicLazyLoadableTest.cs index e90a8ee6..664ff5fa 100644 --- a/OnTopic.Tests/ITopicLazyLoadableTest.cs +++ b/OnTopic.Tests/ITopicLazyLoadableTest.cs @@ -3,6 +3,7 @@ | Client Ignia, LLC | Project Topics Library \=============================================================================================================================*/ +using OnTopic.Associations; using OnTopic.Repositories; using OnTopic.Tests.TestDoubles; using Xunit; @@ -19,6 +20,11 @@ namespace OnTopic.Tests; [ExcludeFromCodeCoverage] public class ITopicLazyLoadableTest { + /*============================================================================================================================ + | PROPERTY: CANCELLATION TOKEN + \---------------------------------------------------------------------------------------------------------------------------*/ + private static CancellationToken CancellationToken => TestContext.Current.CancellationToken; + /*============================================================================================================================ | TEST: IS LOADED: NON-RECURSIVE: IGNORES UNLOADED CHILDREN \---------------------------------------------------------------------------------------------------------------------------*/ @@ -161,7 +167,39 @@ public void IsLoaded_NotLoadedChildren_NeverTriggersLoad() { [Fact] public void EnsureLoaded_NullResolver_DoesNotThrow() { var topic = new Topic("Topic", "Page"); - ((ITopicLazyLoadable)topic).EnsureLoaded(TopicPayload.All); + ((ITopicLazyLoadable)topic).EnsureLoaded(TopicPayload.All, CancellationToken); + } + + /*============================================================================================================================ + | TEST: ENSURE LOADED: CLEARED RELATIONSHIP: DOES NOT RESURRECT + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Registers a deferred entry, then calls on that key. Confirms that a subsequent for never reaches the ; since already purged the deferred entry, there is nothing left to resolve, and the + /// previously cleared relationship isn't resurrected. + /// + [Fact] + public async Task EnsureLoaded_ClearedRelationship_DoesNotResurrect() { + + var topic = new Topic("Test", "Page", null, 1); + var rawLoadable = (ITopicLazyLoadable)topic; + var rawTopic = (ITopicBackingAccessor)topic; + var loader = new TrackingTopicLazyLoader(); + + // Set up and clear via the backing accessor so this doesn't itself trigger a load once LoadState flips to NotLoaded; the + // loader is stamped afterward, ahead of the explicit EnsureLoaded() call below + rawTopic.Relationships.Deferred.SetValue("Related", 999); + rawTopic.Relationships.Clear("Related"); + rawLoadable.Loader = loader; + + await rawLoadable.EnsureLoaded(TopicPayload.Relationships, CancellationToken); + + Assert.False(loader.WasCalled); + Assert.Empty(rawTopic.Relationships.GetValues("Related")); + } /*============================================================================================================================ From c6e644dc5755f823f332b96e2618ebe3621c2b31 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 4 Aug 2026 17:13:42 -0700 Subject: [PATCH 330/337] Serialize `PopulateTargetCollectionAsync()` Previously, both `MapAsync()`'s calls to `PopulateTargetCollectionAsync()` as well as `PopulateTargetCollectionAsync()` own mapping process were handled via task queues, allowing collections of view models to be asynchronously mapped and inserted into the target collection on `Topic`. The problem with this is that the `TopicMultiMap` that underlies `Topic.Relationships` is fundamentally not thread safe. And because it's composed of a collection of collections, it would be very difficult to make it thread safe, and especially because of the fact that the topic references themselves may be referenced multiple times, including via reciprocal associations (e.g., `IncomingRelationships`) and, thus, we can't just map a topic once and then serialize its insertion into the `TopicMultiMap`. This is an unfortunate compromise. That said, in practice, the `ReverseTopicMappingService` is typically used for processing a binding model from a form into a single topic and, thus, won't incur the costs, and even if it did, it's a rare process, not something that's happening multiple times for pretty much every request on the site, as it is with the `TopicMappingService`. This contributes to the concurrency updates to the topic mapping services (#118) in response to the lazy-loading updates (#111). --- .../Reverse/ReverseTopicMappingService.cs | 52 ++++++++++--------- 1 file changed, 27 insertions(+), 25 deletions(-) diff --git a/OnTopic/Mapping/Reverse/ReverseTopicMappingService.cs b/OnTopic/Mapping/Reverse/ReverseTopicMappingService.cs index 57d4acc1..dbbab61c 100644 --- a/OnTopic/Mapping/Reverse/ReverseTopicMappingService.cs +++ b/OnTopic/Mapping/Reverse/ReverseTopicMappingService.cs @@ -183,6 +183,13 @@ public ReverseTopicMappingService(ITopicRepository topicRepository) { /// /// An instance of provided with attributes appropriately mapped. /// + /// + /// Properties are mapped sequentially, in source order, rather than concurrently; this avoids concurrent mutation of the + /// association collections (, , etc.), which aren't thread + /// safe, and which individual property mappers write to on the shared . As a result, an exception + /// thrown while mapping one property surfaces immediately, without waiting for or aggregating exceptions from subsequent + /// properties, and any properties mapped before the failure remain applied to . + /// private async Task MapAsync(object? source, Topic target, string? attributePrefix) { /*-------------------------------------------------------------------------------------------------------------------------- @@ -201,11 +208,9 @@ public ReverseTopicMappingService(ITopicRepository topicRepository) { /*-------------------------------------------------------------------------------------------------------------------------- | Loop through properties, mapping each one \-------------------------------------------------------------------------------------------------------------------------*/ - List taskQueue = []; foreach (var property in typeAccessor.GetMembers(MemberTypes.Property)) { - taskQueue.Add(SetPropertyAsync(source, target, property, attributePrefix)); + await SetPropertyAsync(source, target, property, attributePrefix).ConfigureAwait(false); } - await Task.WhenAll([.. taskQueue]).ConfigureAwait(false); /*-------------------------------------------------------------------------------------------------------------------------- | Return result @@ -535,27 +540,16 @@ private async Task SetReference( /// /// The to pull the binding models from. /// The target to add the mapped objects to. + /// + /// Children are mapped and added sequentially, in order, rather than concurrently; this + /// avoids concurrent mutation on the shared target and guarantees 's + /// resulting order matches the binding model, instead of varying with completion order. + /// private async Task PopulateTargetCollectionAsync( IList sourceList, KeyedTopicCollection targetList ) { - /*-------------------------------------------------------------------------------------------------------------------------- - | Queue up mapping tasks - \-------------------------------------------------------------------------------------------------------------------------*/ - List> taskQueue = []; - - //Map child binding model to target collection on the target - foreach (ITopicBindingModel childBindingModel in sourceList) { - Contract.Assume(childBindingModel.Key); - if (targetList.Contains(childBindingModel.Key)) { - taskQueue.Add(MapAsync(childBindingModel, targetList.GetValue(childBindingModel.Key)!)); - } - else { - taskQueue.Add(MapAsync(childBindingModel)); - } - } - /*-------------------------------------------------------------------------------------------------------------------------- | Remove orphaned topics \-------------------------------------------------------------------------------------------------------------------------*/ @@ -567,15 +561,23 @@ KeyedTopicCollection targetList } /*-------------------------------------------------------------------------------------------------------------------------- - | Process mapping tasks + | Map and add children in source order + >--------------------------------------------------------------------------------------------------------------------------- + | Sequential by design: concurrent MapAsync() calls would mutate non-thread-safe collections on the shared target Topic in + | parallel, and completion-order nondeterminism would make targetList's resulting order unpredictable. \-------------------------------------------------------------------------------------------------------------------------*/ - while (taskQueue.Count > 0) { - var topicTask = await Task.WhenAny(taskQueue).ConfigureAwait(false); - taskQueue.Remove(topicTask); - var topic = await topicTask.ConfigureAwait(false); - if (topic is not null && !targetList.Contains(topic.Key)) { + foreach (ITopicBindingModel childBindingModel in sourceList) { + + Contract.Assume(childBindingModel.Key); + + var topic = targetList.Contains(childBindingModel.Key) + ? await MapAsync(childBindingModel, targetList.GetValue(childBindingModel.Key)!).ConfigureAwait(false) + : await MapAsync(childBindingModel).ConfigureAwait(false); + + if (topic is not null && !targetList.Contains(topic.Key)) { targetList.Add(topic); } + } } From 277edabe4c047541019092743ba10cedef855a83 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 4 Aug 2026 17:26:08 -0700 Subject: [PATCH 331/337] Introduced `StaggeredStubTopicRepository` The `StaggeredStubTopicRepository` performs the same task as `StaggeredTopicLazyLoader` (3359853e), except for `ITopicRepository.Load()` instead of `ITopicLazyLoader.EnsureLoaded()`. That said, because `StaggeredTopicLazyLoader` could have difference instances "stamped" onto each topic, it only required a simple `delay` argument in its constructor. With the `ITopicMappingService`, however, the same instance needs to be used for the entire workflow. As such, instead of a single `delay` argument, it takes the messier approach of accepting a map of topic keys to delays, which it cross-references with every `Load()` request. This provides a test double for aiding in the testing of the `ReverseTopicMappingService`'s `PopulateTargetCollectionAsync())` serialization (c6e644dc). This contributes to the concurrency updates to the topic mapping services (#118) in response to the lazy-loading updates (#111). --- .../StaggeredStubTopicRepository.cs | 68 +++++++++++++++++++ .../TestDoubles/StaggeredTopicLazyLoader.cs | 8 ++- 2 files changed, 75 insertions(+), 1 deletion(-) create mode 100644 OnTopic.Tests/TestDoubles/StaggeredStubTopicRepository.cs diff --git a/OnTopic.Tests/TestDoubles/StaggeredStubTopicRepository.cs b/OnTopic.Tests/TestDoubles/StaggeredStubTopicRepository.cs new file mode 100644 index 00000000..d87ae28e --- /dev/null +++ b/OnTopic.Tests/TestDoubles/StaggeredStubTopicRepository.cs @@ -0,0 +1,68 @@ +/*============================================================================================================================== +| Author Ignia, LLC +| Client Ignia, LLC +| Project Topics Library +\=============================================================================================================================*/ +using OnTopic.Repositories; +using OnTopic.TestDoubles; + +namespace OnTopic.Tests.TestDoubles; + +/*============================================================================================================================== +| CLASS: STAGGERED STUB TOPIC REPOSITORY +\-----------------------------------------------------------------------------------------------------------------------------*/ +/// +/// A that delays by a per-key , letting a test invert completion order relative to call order. +/// +/// +/// +/// This is similar to , except that it staggers calls to , not . +/// +/// +/// This is a sample class intended for test purposes only; it is not designed for use in a production environment. +/// +/// +[ExcludeFromCodeCoverage] +internal sealed class StaggeredStubTopicRepository: StubTopicRepository { + + /*============================================================================================================================ + | PRIVATE FIELDS + \---------------------------------------------------------------------------------------------------------------------------*/ + private readonly IReadOnlyDictionary _delaysByKey; + + /*============================================================================================================================ + | CONSTRUCTOR + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Initializes a new instance of the with a delay for each unique key that + /// should complete out of call order. + /// + /// A map of unique topic key to the delay that should precede its resolution. + public StaggeredStubTopicRepository(IReadOnlyDictionary delaysByKey) { + _delaysByKey = delaysByKey; + } + + /*============================================================================================================================ + | METHOD: LOAD + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + public override async Task Load( + string uniqueKey, + Topic? referenceTopic = null, + TopicPayload payload = TopicPayload.None, + int depth = 0 + ) { + + // Delay resolution of this key, if configured + if (_delaysByKey.TryGetValue(uniqueKey, out var delay) && delay > TimeSpan.Zero) { + await Task.Delay(delay).ConfigureAwait(false); + } + + // Delegate to the base implementation to perform the actual lookup + return await base.Load(uniqueKey, referenceTopic, payload, depth).ConfigureAwait(false); + + } + +} //Class \ No newline at end of file diff --git a/OnTopic.Tests/TestDoubles/StaggeredTopicLazyLoader.cs b/OnTopic.Tests/TestDoubles/StaggeredTopicLazyLoader.cs index 964735e9..12d2e0a2 100644 --- a/OnTopic.Tests/TestDoubles/StaggeredTopicLazyLoader.cs +++ b/OnTopic.Tests/TestDoubles/StaggeredTopicLazyLoader.cs @@ -16,7 +16,13 @@ namespace OnTopic.Tests.TestDoubles; /// genuinely complete out of source order. /// /// -/// This is a sample class intended for test purposes only; it is not designed for use in a production environment. +/// +/// This is similar to , except that it staggers calls to , not . +/// +/// +/// This is a sample class intended for test purposes only; it is not designed for use in a production environment. +/// /// [ExcludeFromCodeCoverage] internal sealed class StaggeredTopicLazyLoader(TimeSpan delay): ITopicLazyLoader { From 909121db8387cffea18b2279432ba08e84e62eee Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 4 Aug 2026 17:30:48 -0700 Subject: [PATCH 332/337] Introduced `NestedReferenceAttribute` model The `NestedReferenceAttributeTopicBindingModel` provides a binding model for testing the serialization fix of the `ReverseTopicMappingService`'s `PopulateTargetCollectionAsync()` method (c6e644dc). This contributes to the concurrency updates to the topic mapping services (#118) in response to the lazy-loading updates (#111). --- ...stedReferenceAttributeTopicBindingModel.cs | 26 +++++++++++++++++++ 1 file changed, 26 insertions(+) create mode 100644 OnTopic.Tests/BindingModels/NestedReferenceAttributeTopicBindingModel.cs diff --git a/OnTopic.Tests/BindingModels/NestedReferenceAttributeTopicBindingModel.cs b/OnTopic.Tests/BindingModels/NestedReferenceAttributeTopicBindingModel.cs new file mode 100644 index 00000000..9ce23ae0 --- /dev/null +++ b/OnTopic.Tests/BindingModels/NestedReferenceAttributeTopicBindingModel.cs @@ -0,0 +1,26 @@ +/*============================================================================================================================== +| Author Ignia, LLC +| Client Ignia, LLC +| Project Topics Library +\=============================================================================================================================*/ +using OnTopic.ViewModels.BindingModels; + +namespace OnTopic.Tests.BindingModels; + +/*============================================================================================================================== +| BINDING MODEL: NESTED REFERENCE ATTRIBUTE TOPIC +\-----------------------------------------------------------------------------------------------------------------------------*/ +/// +/// Provides a minimal implementation of a custom topic binding model with both a scalar value and a reference property, for +/// use as an item within a collection. +/// +/// +/// This is a sample class intended for test purposes only; it is not designed for use in a production environment. +/// +public class NestedReferenceAttributeTopicBindingModel : AttributeDescriptorTopicBindingModel { + + public NestedReferenceAttributeTopicBindingModel(string key) : base(key, "TextAttributeDescriptor") { } + + public AssociatedTopicBindingModel? BaseTopic { get; set; } + +} //Class \ No newline at end of file From 23f4adfe9ab32f64b83e04514757c7fe9162fdd5 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 4 Aug 2026 17:34:25 -0700 Subject: [PATCH 333/337] Added unit test for topic mapping serialization This provides a unit test for serialization fix of the `ReverseTopicMappingService`'s `PopulateTargetCollectionAsync()` method (c6e644dc), using the newly introduced `StaggeredStubTopicRepository` (277edabe) and `NestedReferenceAttributeTopicBindingModel` (909121db). This contributes to the concurrency updates to the topic mapping services (#118) in response to the lazy-loading updates (#111). --- .../ReverseTopicMappingServiceTest.cs | 47 +++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/OnTopic.Tests/ReverseTopicMappingServiceTest.cs b/OnTopic.Tests/ReverseTopicMappingServiceTest.cs index 6b352628..4d738526 100644 --- a/OnTopic.Tests/ReverseTopicMappingServiceTest.cs +++ b/OnTopic.Tests/ReverseTopicMappingServiceTest.cs @@ -15,6 +15,7 @@ using OnTopic.TestDoubles.Metadata; using OnTopic.Tests.BindingModels; using OnTopic.Tests.Fixtures; +using OnTopic.Tests.TestDoubles; using Xunit; namespace OnTopic.Tests; @@ -325,6 +326,52 @@ public async Task Map_NestedTopics_ReturnsMappedTopic() { } + /*============================================================================================================================ + | TEST: MAP: NESTED TOPICS: STAGGERED COMPLETION: PRESERVES SOURCE ORDER + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Establishes a backed by a whose + /// per-item topic reference lookups resolve out of call order: The first-declared item resolves slowest, the last-declared + /// item resolves instantly. Confirms nested topics still land in the binding model's source order, since maps and adds each child sequentially rather than racing completions. + /// + [Fact] + public async Task Map_NestedTopics_StaggeredCompletion_PreservesSourceOrder() { + + // Declared in call order; delays fall in reverse, so the first-added item resolves last + List<(string UniqueKey, TimeSpan Delay)> attributes = [ + ("Root:Configuration:ContentTypes:Attributes:Key", TimeSpan.FromMilliseconds(120)), + ("Root:Configuration:ContentTypes:Attributes:ContentType", TimeSpan.FromMilliseconds(60)), + ("Root:Configuration:ContentTypes:Attributes:Title", TimeSpan.Zero) + ]; + + var delaysByKey = attributes.ToDictionary(attribute => attribute.UniqueKey, attribute => attribute.Delay); + var topicRepository = new StaggeredStubTopicRepository(delaysByKey); + var mappingService = new ReverseTopicMappingService(topicRepository); + var bindingModel = new ContentTypeDescriptorTopicBindingModel("Test"); + + for (var i = 0; i < attributes.Count; i++) { + bindingModel.Attributes.Add( + new NestedReferenceAttributeTopicBindingModel($"Attribute{i + 1}") { + BaseTopic = new() { + UniqueKey = attributes[i].UniqueKey + } + } + ); + } + + var topic = new ContentTypeDescriptor("Test", "ContentTypeDescriptor"); + var target = (ContentTypeDescriptor?)await mappingService.MapAsync(bindingModel, topic); + var container = target?.Children.GetValue("Attributes"); + + Assert.NotNull(container); + Assert.Equal( + Enumerable.Range(1, attributes.Count).Select(i => $"Attribute{i}"), + container.Children.Select(child => child.Key) + ); + + } + /*============================================================================================================================ | TEST: MAP: TOPIC REFERENCES: RETURNS MAPPED TOPIC \---------------------------------------------------------------------------------------------------------------------------*/ From f0c65ea20b851003c1530bcb1112a80247e463b8 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 4 Aug 2026 17:54:37 -0700 Subject: [PATCH 334/337] Ensure target topic is fully loaded When mapping a binding model to a topic via the `ReverseTopicMappingService`, we need to make sure, at minimum, that the extended attributes are loaded, as otherwise unchanged values will be marked dirty, potentially resulting in e.g., the blob (in the `SqlTopicRepository`) being versioned despite no actual changes. To solve this, I `EnsureLoaded()` on `MapAsync()`. In addition, if any nested topics are present, I `EnsureLoaded()` children on both the topic as well as its nested topic container via `SetNestedTopicsAsync()`. This isn't strictly necessary, since these would be lazy loaded on access, but because property calls can only load synchronously, doing this preemptively allows the call to be asynchronous. This contributes to the concurrency updates to the `ReverseTopicMappingService` (part of #118) in response to the lazy-loading updates (#111). --- .../Reverse/ReverseTopicMappingService.cs | 23 +++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/OnTopic/Mapping/Reverse/ReverseTopicMappingService.cs b/OnTopic/Mapping/Reverse/ReverseTopicMappingService.cs index dbbab61c..6aac76a3 100644 --- a/OnTopic/Mapping/Reverse/ReverseTopicMappingService.cs +++ b/OnTopic/Mapping/Reverse/ReverseTopicMappingService.cs @@ -197,6 +197,14 @@ public ReverseTopicMappingService(ITopicRepository topicRepository) { \-------------------------------------------------------------------------------------------------------------------------*/ if (source is null) return target; + /*-------------------------------------------------------------------------------------------------------------------------- + | Warm extended attributes + >--------------------------------------------------------------------------------------------------------------------------- + | Without this, TrackedRecordCollection.SetValue() potentially runs against an unloaded extended attributes, and thus marks + | attributes as dirty even if they're unchanged, causing needless version rows on save. + \-------------------------------------------------------------------------------------------------------------------------*/ + await ((ITopicLazyLoadable)target).EnsureLoaded(TopicPayload.ExtendedAttributes).ConfigureAwait(false); + /*-------------------------------------------------------------------------------------------------------------------------- | Validate model \-------------------------------------------------------------------------------------------------------------------------*/ @@ -449,6 +457,13 @@ private async Task SetNestedTopicsAsync( \-------------------------------------------------------------------------------------------------------------------------*/ var sourceList = (IList?)memberAccessor.GetValue(source) ?? new List(); + /*-------------------------------------------------------------------------------------------------------------------------- + | Warm target's children + >--------------------------------------------------------------------------------------------------------------------------- + | Replaces the Children getter's synchronous autoload with an explicit, asynchronous warm-up prior to the below probe + \-------------------------------------------------------------------------------------------------------------------------*/ + await ((ITopicLazyLoadable)target).EnsureLoaded(TopicPayload.Children).ConfigureAwait(false); + /*-------------------------------------------------------------------------------------------------------------------------- | Establish target collection to store mapped topics \-------------------------------------------------------------------------------------------------------------------------*/ @@ -458,6 +473,14 @@ private async Task SetNestedTopicsAsync( container.IsHidden = true; } + /*-------------------------------------------------------------------------------------------------------------------------- + | Warm container's children + >--------------------------------------------------------------------------------------------------------------------------- + | The container can be NotLoaded even when target is loaded; PopulateTargetCollectionAsync()'s Contains() check for existing + | children as well as it's check for orphans require the complete set + \-------------------------------------------------------------------------------------------------------------------------*/ + await ((ITopicLazyLoadable)container).EnsureLoaded(TopicPayload.Children).ConfigureAwait(false); + /*-------------------------------------------------------------------------------------------------------------------------- | Map the topics from the source collection, and add them to the target collection \-------------------------------------------------------------------------------------------------------------------------*/ From 59a8b85c440ad84e87185db6fd8acf37c345ddb5 Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 4 Aug 2026 18:13:56 -0700 Subject: [PATCH 335/337] Optionally allow tracking load counting On the `TrackingTopicLazyLoader` test double, update it to track every load (via a new `_payloads` field) and, optionally, `SetLoadState()` for the topic, like a normal `ITopicLazyLoader` would be expected to do on `EnsureLoaded()`. This updates `WasCalled` to be readonly, automatically reflecting whether there are any calls recorded in the `_payloads` field. This will be necessary to test the warmup of the target topic(s) via the `ReverseTopicMappingService` (f0c65ea2). This contributes to the concurrency testing of the `ReverseTopicMappingService` (part of #118) in response to the lazy-loading updates (#111). --- .../TestDoubles/TrackingTopicLazyLoader.cs | 38 +++++++++++++++++-- 1 file changed, 35 insertions(+), 3 deletions(-) diff --git a/OnTopic.Tests/TestDoubles/TrackingTopicLazyLoader.cs b/OnTopic.Tests/TestDoubles/TrackingTopicLazyLoader.cs index e340a958..793f9d67 100644 --- a/OnTopic.Tests/TestDoubles/TrackingTopicLazyLoader.cs +++ b/OnTopic.Tests/TestDoubles/TrackingTopicLazyLoader.cs @@ -13,8 +13,20 @@ namespace OnTopic.Tests.TestDoubles; /// /// A minimal spy that records whether it was invoked, without performing any actual loading. /// +/// +/// By default, this doesn't mutate , so a stamped topic remains +/// even after a call, letting tests assert that a specific code path either suppresses or triggers autoloading. Pass +/// to instead simulate a real loader's fill, marking the requested payload on each call, when a test needs to confirm that a caller warms a payload exactly once +/// rather than relying on this spy's inertness to inflate the count. +/// [ExcludeFromCodeCoverage] -internal sealed class TrackingTopicLazyLoader : ITopicLazyLoader { +internal sealed class TrackingTopicLazyLoader(bool markLoaded = false) : ITopicLazyLoader { + + /*============================================================================================================================ + | PRIVATE FIELDS + \---------------------------------------------------------------------------------------------------------------------------*/ + private readonly List _payloads = []; /*============================================================================================================================ | PROPERTY: WAS CALLED @@ -22,14 +34,34 @@ internal sealed class TrackingTopicLazyLoader : ITopicLazyLoader { /// /// Returns if was invoked. /// - public bool WasCalled { get; private set; } + public bool WasCalled => _payloads.Count > 0; + + /*============================================================================================================================ + | PROPERTY: CALL COUNT + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Returns the number of times was invoked. + /// + public int CallCount => _payloads.Count; + + /*============================================================================================================================ + | PROPERTY: PAYLOADS + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Returns the passed to each invocation of , in + /// call order. + /// + public IReadOnlyList Payloads => _payloads; /*============================================================================================================================ | METHOD: ENSURE LOADED \---------------------------------------------------------------------------------------------------------------------------*/ /// Task ITopicLazyLoader.EnsureLoaded(Topic topic, TopicPayload payload, CancellationToken cancellationToken) { - WasCalled = true; + _payloads.Add(payload); + if (markLoaded) { + ((ITopicLazyLoadable)topic).SetLoadState(payload, LoadState.Loaded); + } return Task.CompletedTask; } From f2355088aa10149969cfaa630e1ccf321111dc7d Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 4 Aug 2026 18:16:49 -0700 Subject: [PATCH 336/337] Added unit test for topic mapping warmup This tests the warmup of the target topic(s) via the `ReverseTopicMappingService` (f0c65ea2), relying on the updates to the `TrackingTopicLazyLoader` to support counting and marking loads. This contributes to the concurrency testing of the `ReverseTopicMappingService` (part of #118) in response to the lazy-loading updates (#111). --- .../ReverseTopicMappingServiceTest.cs | 60 +++++++++++++++++++ 1 file changed, 60 insertions(+) diff --git a/OnTopic.Tests/ReverseTopicMappingServiceTest.cs b/OnTopic.Tests/ReverseTopicMappingServiceTest.cs index 4d738526..c1caa9a5 100644 --- a/OnTopic.Tests/ReverseTopicMappingServiceTest.cs +++ b/OnTopic.Tests/ReverseTopicMappingServiceTest.cs @@ -372,6 +372,66 @@ public async Task Map_NestedTopics_StaggeredCompletion_PreservesSourceOrder() { } + /*============================================================================================================================ + | TEST: MAP: SPARSE TOPIC: FILLS EXTENDED ATTRIBUTES ONCE + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Maps a scalar-only binding model onto a target stamped with a whose are . Confirms warms exactly once at the start of the map, rather than leaving it to the attribute + /// collection's own synchronous autoload. + /// + [Fact] + public async Task Map_ScalarProperties_FillsExtendedAttributesOnce() { + + var bindingModel = new TextAttributeTopicBindingModel("Test") { + ContentType = "TextAttributeDescriptor", + DefaultValue = "World" + }; + + var target = new TextAttributeDescriptor("Test", "TextAttributeDescriptor"); + var loader = new TrackingTopicLazyLoader(markLoaded: true); + + ((ITopicLazyLoadable)target).Loader = loader; + target.Attributes.LoadState = LoadState.NotLoaded; + + _ = await _mappingService.MapAsync(bindingModel, target); + + Assert.Equal(1, loader.CallCount); + Assert.Equal(TopicPayload.ExtendedAttributes, loader.Payloads[0]); + + } + + /*============================================================================================================================ + | TEST: MAP: NESTED TOPICS: FILLS CONTAINER CHILDREN + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Maps a nested-topic binding model onto a target whose Attributes container is stamped with its own and left , even though the target's own are already loaded. Confirms warms the container + /// independently before PopulateTargetCollectionAsync probes its existing children. + /// + [Fact] + public async Task Map_NestedTopics_FillsContainerChildren() { + + var bindingModel = new ContentTypeDescriptorTopicBindingModel("Test"); + + bindingModel.Attributes.Add(new TextAttributeTopicBindingModel("Attribute1")); + + var target = new ContentTypeDescriptor("Test", "ContentTypeDescriptor"); + var container = new Topic("Attributes", "List", target); + var containerLoader = new TrackingTopicLazyLoader(markLoaded: true); + + ((ITopicLazyLoadable)container).Loader = containerLoader; + container.Children.LoadState = LoadState.NotLoaded; + + _ = (ContentTypeDescriptor?)await _mappingService.MapAsync(bindingModel, target); + + Assert.Equal(1, containerLoader.CallCount); + Assert.Equal(TopicPayload.Children, containerLoader.Payloads[0]); + + } + /*============================================================================================================================ | TEST: MAP: TOPIC REFERENCES: RETURNS MAPPED TOPIC \---------------------------------------------------------------------------------------------------------------------------*/ From 4857676fe75180e2f40cc1bd0dbb6d00a0cdca4b Mon Sep 17 00:00:00 2001 From: Jeremy Caney Date: Tue, 4 Aug 2026 19:56:14 -0700 Subject: [PATCH 337/337] Defer `GetContentTypeDescriptors()` to first use Instead of blocking construction by potentially eagerly loading the entire `Root:Configuration` tree, instead opt to quickly initialize the `ReverseTopicMappingService`, and then call `GetContentTypeDescriptors()` on its first use. This addresses a blocking call in the `ReverseTopicMappingService` constructor, plus a potentially stale reference to the `Configuration` topic graph. In practice, we generally expect this data will be cached as part of the underlying `ITopicRepository`, even if it's not using e.g., the `CachedTopicRepository`, and so this wasn't actually buying us any performance benefit, while the staleness concern is introduced if the underlying layer doesn't do that (e.g., if it relied and a fast, no-cache persistence layer). This is the final update to make the topic mapping services (and, in this case, the `ReverseTopicMappingService`) compatible (#118) with concurrency concerns introduced by lazy loading (#111). --- .../Reverse/ReverseTopicMappingService.cs | 41 ++++++++++++------- 1 file changed, 27 insertions(+), 14 deletions(-) diff --git a/OnTopic/Mapping/Reverse/ReverseTopicMappingService.cs b/OnTopic/Mapping/Reverse/ReverseTopicMappingService.cs index 6aac76a3..ca892ce5 100644 --- a/OnTopic/Mapping/Reverse/ReverseTopicMappingService.cs +++ b/OnTopic/Mapping/Reverse/ReverseTopicMappingService.cs @@ -25,7 +25,6 @@ public class ReverseTopicMappingService : IReverseTopicMappingService { | PRIVATE VARIABLES \---------------------------------------------------------------------------------------------------------------------------*/ readonly ITopicRepository _topicRepository; - readonly ContentTypeDescriptorCollection _contentTypeDescriptors; /*============================================================================================================================ | CONSTRUCTOR @@ -44,16 +43,6 @@ public ReverseTopicMappingService(ITopicRepository topicRepository) { | Set dependencies \-------------------------------------------------------------------------------------------------------------------------*/ _topicRepository = topicRepository; - _contentTypeDescriptors = topicRepository.GetContentTypeDescriptors(); - - /*-------------------------------------------------------------------------------------------------------------------------- - | Validate dependencies - \-------------------------------------------------------------------------------------------------------------------------*/ - Contract.Assume( - _contentTypeDescriptors, - $"The {nameof(ITopicRepository.GetContentTypeDescriptors)}() method returned null. This could indicate a corrupt " + - $"or data source." - ); } @@ -133,7 +122,7 @@ public ReverseTopicMappingService(ITopicRepository topicRepository) { Contract.Assume(source.ContentType, nameof(source.ContentType)); //Ensure the content type is valid - if (!_contentTypeDescriptors.Contains(source.ContentType)) { + if (!GetContentTypeDescriptors().Contains(source.ContentType)) { throw new MappingModelValidationException( $"The {nameof(source)} object (with the key '{source.Key}') has a content type of '{source.ContentType}'. There " + $"are no matching content types in the ITopicRepository provided. This suggests that the binding model is invalid. " + @@ -168,6 +157,30 @@ public ReverseTopicMappingService(ITopicRepository topicRepository) { } + /*============================================================================================================================ + | PRIVATE: GET CONTENT TYPE DESCRIPTORS + \---------------------------------------------------------------------------------------------------------------------------*/ + /// + /// Retrieves the from the . + /// + /// + /// Called per-use rather than cached into a field, since content types can be added after this service is constructed, and + /// a local cache would silently exclude any updates for the life of the service. Further, , + /// the base class for every production in this library, already caches the result after the + /// first call and maintains the live collection in place (e.g. Delete refreshes it), so the per-call access here is + /// expected to be cheap, acknowledging that's a property of that base class, not a guarantee of the interface itself. + /// + private ContentTypeDescriptorCollection GetContentTypeDescriptors() { + var contentTypeDescriptors = _topicRepository.GetContentTypeDescriptors(); + Contract.Assume( + contentTypeDescriptors, + $"The {nameof(ITopicRepository.GetContentTypeDescriptors)}() method returned null. This could indicate a corrupt " + + $"data source." + ); + return contentTypeDescriptors; + } + /*============================================================================================================================ | PRIVATE: MAP (TOPIC) \---------------------------------------------------------------------------------------------------------------------------*/ @@ -209,7 +222,7 @@ public ReverseTopicMappingService(ITopicRepository topicRepository) { | Validate model \-------------------------------------------------------------------------------------------------------------------------*/ var typeAccessor = TypeAccessorCache.GetTypeAccessor(source.GetType()); - var contentTypeDescriptor = _contentTypeDescriptors.GetValue(target.ContentType); + var contentTypeDescriptor = GetContentTypeDescriptors().GetValue(target.ContentType); BindingModelValidator.ValidateModel(typeAccessor, contentTypeDescriptor, attributePrefix); @@ -252,7 +265,7 @@ private async Task SetPropertyAsync( | Establish per-property variables \-------------------------------------------------------------------------------------------------------------------------*/ var configuration = memberAccessor.Configuration; - var contentTypeDescriptor = _contentTypeDescriptors.GetValue(target.ContentType); + var contentTypeDescriptor = GetContentTypeDescriptors().GetValue(target.ContentType); var compositeAttributeKey = configuration.GetCompositeAttributeKey(attributePrefix); Contract.Assume(contentTypeDescriptor, nameof(contentTypeDescriptor));