Hierarchical API analysis

[codestiff]

Suppose we have some data (below) and we want to initialize the entities into their hierarchical tree. Intuitively, we would think adding relationship links in both directions. However, given these are immutable data structures (and that is a "good" thing [at least for now]). Adding the backlinks will always be incomplete because link will be missing the relationships that it is being added to (I can add more details if needed).

    (let [keyword-entities (fn
                             [paragraph]
                             (let [keywords (->>
                                             (clojure.string/split paragraph #"\s+")
                                             (concat [name])
                                             (map #(clojure.string/replace % #"\W" "")))]
                               (for [kw keywords]
                                 {::entity/kind ::item-search-keywords
                                  ::entity/attributes {:keyword kw}})))

          item-1-description "So many wonder kittens to play with. Try them all."
          item-2-description "Cold cereal. Goes great with milk!"

          item-1 {::entity/kind ::items
                  ::entity/attributes {:sku "ff-0012"
                                       :name "kitten"
                                       :description item-1-description
                                       :price 128.99}

                  ::entity/relationships {:keywords (keyword-entities item-1-description)}}

          item-2 {::entity/kind ::items
                  ::entity/attributes {:sku "gd-4921"
                                       :name "cereal"
                                       :description item-2-description
                                       :price 4.78}

                  ::entity/relationships {:item item-1
                                          :keywords (keyword-entities item-2-description)}}

          shopping-cart-item-1 {::entity/kind ::shopping-cart-items
                                ::entity/relationships {:item item-1}}

          shopping-cart-item-2 {::entity/kind ::shopping-cart-items
                                ::entity/relationships {:item item-2}}

          shopping-cart {::entity/kind ::shopping-carts
                         ::entity/attributes {:user-id "user-1"}
                         ::entity/relationships {:shopping-cart-items [shopping-cart-item-1
                                                                       shopping-cart-item-2]}}]

(core/init-rels
         fs
         context
         shopping-cart)

Maybe the underlying assumption should be that entities given in a tree are by definition not going to have backlinks and the API will know how to work will that. After all, we can add backlinks (ad hoc) when request a child entity of a tree.

[codestiff]

There is one "problem" with the above approach. The validation logic will try to validate an entity when it is initialized. If we want an entity to have a not nil reference, shouldn't it have that relationship at initialization? To complicate things, if we add a backlink to relate the reference, it may not be persisted which means it may not have an id. We can't expect the reference value to be calculated until write, which means we may want some sentinel value like: ::not-persisted

The write logic may need to include reevaluating the ref-attributes (by setting nil to all refs not defined by the relationships).

[codestiff]

Maybe ::parent makes more sense when creating using a tree.
And the associating reference-attributes from relationships should be if ::parent and if the entity is missing an ::ident

Using ::ident is probably wrong not all references are going to be using the ::ident the attributes need to be loaded.

Maybe simply, ::not-set or ::to-be-determined or ::placeholder or ::unset

I think ::pending might be the best

And ::pending means the reference has properties which are waiting until write in order to be determined.

Now the question becomes is there a way to mark entities that are ::pending (in order to facilitate traversal)? This may not be necessary (maybe we just traverse using what is in relationships).