ONE objects in storage form a directed graph. When ID object links are used they may form cycles, without ID links cycles are not possible (one would have to calculate the SHA-256 hashes of objects directly or indirectly pointing at one another).
This module implements a general ONE object graph iterator. It takes the hash of a concrete ONE object and then iterates over every single reachable node in the graph using a DEPTH FIRST strategy to avoid too much parallelism (too many open paths, potentially too much memory usage). It calls the given callback function for each ONE object node that it visits.
It only descends if the linked file is a ONE object, it does not descend for links to BLOBs. We know those always are leave nodes though and those links are made available with the current object.
Methods
(static) createStopIteratorError() → {StopIteratorError}
Convenience function which creates an Error
object with its name property set to
StopIteratorError
.
Returns:
Returns an error object with name property StopIteratorError
Type: StopIteratorError
(async, static) iterateGraphFromObjectBottomUp(hash, cb, optionsopt) → {Promise.<boolean>}
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
hash |
SHA256Hash | The SHA-256 hash of the ONE object in storage that is to be used as root node |
|
cb |
function | Callback function called for each node (ONE object, ONE ID object if ID object iteration is enabled, BLOB or CLOB). If the callback function returns a promise the iteration waits until the promise resolves before proceeding. Return values are ignored. |
|
options |
ObjectGraphIteratorOptions |
<optional> |
An optional options object |
Function to iterate over a ONE object graph in storage starting from a given root node. The function returns a promise that resolves when all nodes have been visited, or rejects when there was an error - for example in the given per-node callback function.
-
Depth first: The algorithm descends the first link it finds in an object, and only when it went all the way down and visited all nodes on the linked object does it visit the next link in the current object.
-
Direction either is top-down (default) or bottom-up. Top down: The algorithm calls the given callback function for each node before it visits any linked nodes. That means the callback function is first called for parent nodes, and then for the children (descending into the graph). Bottom up: The algorithm only calls the given callback function for each node after it has visited all its linked nodes. That means the callback function is called for leaf nodes first, then for its parents.
-
Every node is sent only once even if it is linked more than once.
-
Child node iteration order is consistent but depends on the recipe and the data: If your Reference objects are in an array their order may be either determined by your application or by ONE, which sorts them alphabetically to ensure microdata that always produces the same hash.
-
Versioned and unversioned concrete object hash links: The callback is called for both kinds of ONE objects. The objects are loaded from storage and the callback is called.
-
Clob/Blob hash links: Those are iterated over just like the ONE object and ONE ID object nodes. That means that the callback is called, but the data it receives is slightly different from the one for ONE [ID] objects, see IteratorCbParam union type.
-
ID object links: The behavior when iterating over ID links is configurable (option parameter). The callback function is called for each version or only for the latest version. Cycles created by ID object links are detected and iterated over only once.
You can stop iteration without the iterator promise rejecting by throwing an Error
whose name
property is "StopIteratorError" from within the callback function. Any other error
causes the iterator promise to reject with that error.
Returns:
Returns a promise that resolves when the iteration is over. It
resolves with true
when the iteration completed, i.e. all objects in the graph were
visited. It resolves with false
if the iterator was stopped by the callback using an Error
whose name property is StopIteratorError
.
Type: Promise.<boolean>
Type Definitions
IteratorCbParam
The callback function given to the object-graph-iterator to call for each object receives an object of this type as its parameter.
Type:
- object
Properties:
Name | Type | Description |
---|---|---|
type |
'hash' | 'id' | 'blob' | 'clob' |
ObjectGraphIteratorOptions
The options object parameter of the
iterateGraphFromObjectBottomUp
function.
Type:
- object
Properties:
Name | Type | Attributes | Description |
---|---|---|---|
idLinkIteration |
0 | 1 | 2 |
<optional> |
How to handle ID hash links: Not at all, iterate to the latest version (hash), iterate over all versions (hashes) |
includeFileSize |
boolean |
<optional> |
If |
HashAndIdHashAndTimestamp
A concrete version hash of a versioned object identified by an ID hash, and the timestamp of version map entry creation for that concrete hash.
Type:
- object
Properties:
Name | Type | Description |
---|---|---|
hash |
SHA256Hash | |
idHash |
SHA256IdHash | |
timestamp |
number |