Module: object-graph-bottom-up-iterator

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.

Source:

Methods

(static) createStopIteratorError() → {StopIteratorError}

Convenience function which creates an Error object with its name property set to StopIteratorError.

Source:
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.

Source:
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'
Source:

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 true the callback's IteratorCbParam parameter is going to include the byte includeFileSize of the current node/object. When storage encryption is enabled the includeFileSize will be +-16 bytes of the true value due to random padding of 32 bytes added to the encrypted container. iterateGraphFromAllVersionsOfIdObject because when iterating over an ID object the iterator automatically uses each version's timestamp.
Source:

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
Source: