back to main project page
The classes and types you should be aware of when adapting or extending treeifier are:
- class Treeifier
- class TreeifierNode
- enum TreeifierNodeType
- type NodeProcessorFunction
This class is the main class of the treeifier library. It allows to analyze and render the input object i.e. a client application should use an instance of this class to process an input object.
const treeifier = new Treeifier();
const treeRepresentation: string = treeifier.process( myObject );
console.log( treeRepresentation );e.g. const treeifier = new Treeifier(myProcessor);
| parameters | types | optional | description |
|---|---|---|---|
| nodeProcessorCallback | NodeProcessorFunction | yes | the function that generate the representation of each node (default to standard processor) |
Important:
if the nodeProcessorCallback parameter is not provided in the constructor, a standard (default) processor will be used when process(..)or parse() methods are called, unless a processor is specified in the call.
| case | behavior | |
|---|---|---|
| 1 | no processor defined in the constructor no processor specified in the methods parameters |
→ default processor will be used |
| 2 | no processor defined in the constructor a processor is specified in the methods parameters |
→ processor of the method will be used (e.g. process( myObject, 'root', myProcessor) ) |
| 3 | processor defined in the constructor no processor specified in the methods parameters |
→ processor of the constructor will be used |
| 4 | processor defined in the constructor a processor is specified in the methods parameters |
→ processor of the method will be used |
This function is giving the representation (according to the processor function) corresponding to the input object back. This is the primary method you'd probably use all the time.
e.g. mytreeifier.process(myObject,'root-object');
| parameters | types | optional | description |
|---|---|---|---|
| root | any | no | the input object to be analyzed |
| label | string | yes | the "name" of the input object (default to "root") |
| nodeProcessorCallback | NodeProcessorFunction | yes | the function that generate the representation of each node (default to standard processor) |
This function is analyzing the input object and giving the corresponding TreeifierNode structure back. This method is provided for your conveniance e.g. for debugging purposes.
e.g. mytreeifier.parse(myObject,'root-object', myProcessor);
| parameters | types | optional | description |
|---|---|---|---|
| root | any | no | the input object to be analyzed |
| label | string | yes | the "name" of the input object (default to "root") |
| nodeProcessorCallback | NodeProcessorFunction | yes | the function that generate the representation of each node (default to standard processor) |
This class is the basic element of the internal representation of the input object as generated by treeifier. The internal representation is a tree of TreeifierNode.
One TreeifierNode instance corresponds to a "property / value / treeifier analysis" combination for each property of the input object or its sub-properties (recursive).
- you may use the class members/properties and the toString() method while developing your own processor function. These information help to generate appropriate representations, depending on the node.
- You should hardly have to instanciate this class on your own: treeifier is doing the job for you when parsing the input object and use the internaly generated tree to output the final representation.
| member | type | restriction | description |
|---|---|---|---|
| key | string | ro | the property of the input object |
| value | any | ro | the original value of the object property |
| processResult | any | rw | the representation of the node as generated by the processor function. Used by Treeifier.process(..) to output the representation. |
| path | string | ro | path to the analyzed property within the original input object e.g. myObject.name.firstname |
| index | number | ro | the index of the property in the object (e.g. as per Object.keys(...)) |
| parent | TreeifierNode or null | ro | the parent TreeifierNode (if any, depending on the inpüut object) |
| nodeType | TreeifierNodeTypes | ro | the type of the value as analyzed by Treeifier (see the node types section below) |
| isLeaf | boolean | ro | is this node a leaf of the structure? Depends on the node type and the setup (see the node types section below) |
| isBranch | boolean | ro | is this node a branch of the structure? Depends on the node type and the setup (see the node types section below) |
| isValue | boolean | ro | may the value directly be interpreted/rendered? Depends on the node type and the setup (see the node types section below) |
| depth | number | ro | how deep in the tree representation is this node situated (starting at depth level 0 = root node) |
| ancestors | Array | ro | all nodes up to the root of the structure |
| maxIndex | number | ro | amount of siblings to the current node |
| isCircular | boolean | ro | the value is referencing an object which is in the ancestors list i.e. it's a circular reference |
| prefix | string | rw | the prefixing "tree structure" (branch parts) as rendered in prefix + joint + key + value. Automatically generated at the node creation time. |
| joint | string | rw | the "joint" between a leaf and its branch as rendered in prefix + joint + key + value. Automatically generated at the node creation time. |
| children | Array | ro | list of child nodes (branches or leafs) |
For each property of an analyzed object (or sub-object), we have the following relationship:
| object | node |
|---|---|
| property name | → TreeifierNode.key |
| property value | → TreeifierNode.value |
| property value type | → TreeifierNode.nodeType |
| property value representation | → TreeifierNode.asString() |
| method | description |
|---|---|
| constructor(key: string, value: any, index: number, parent: TreeifierNode or null) | see class description above |
| toString(): string; | this function is providing a default representation of the property value as analyzed by treeifier, depending on the value type (see the node types section below) |
This enum contains all the value types as "recognized" by treeifier. It enum provides the values for setting the TreeifierNode property nodeType
When the value of the object property ... is, then the nodeType of the corresponding TreeNode is set to ...
treeifier is analyzing the input object, trying to figure out what are the types of the properties inside this object...
As a result of the analysis of each property, a TreeifierNode instance is created, storing the type of the value identified by treeifier for the given input object property value: this is stored as the nodeType member of the TreeifierNode.
This type information will also be utilized to output a textual representation (string) of each node within the helper function Treeifier.toString(). This method offers a convenient way of transforming a node value into a string, following some standard behavior. In other words, it is assuming some default transformation rules that should match most of the needs in a processor function.
Hence, the analyze made by treeifier should identify the following types of property values automatically:
| property value | nodeType | asString() output | remark |
|---|---|---|---|
null |
TreeifierNodeTypes.empty | null |
|
undefined |
TreeifierNodeTypes.empty | undefined |
|
'a string' |
TreeifierNodeTypes.string | a string |
single or double quotes |
'姓名' |
TreeifierNodeTypes.string | 姓名 |
unicode chars |
'\u59d3\u540d' |
TreeifierNodeTypes.string | 姓名 |
unicode chars |
'2020-01-01' |
TreeifierNodeTypes.string | 2020-01-01 |
no date-string parsing (as of now) |
123 |
TreeifierNodeTypes.number | 123 |
|
NaN |
TreeifierNodeTypes.number | NaN |
|
infinity |
TreeifierNodeTypes.number | Infinity |
|
new Date(2020,0,1) |
TreeifierNodeTypes.date | 1.1.2020 |
any date object; output as local date string |
true |
TreeifierNodeTypes.boolean | true |
|
false |
TreeifierNodeTypes.boolean | false |
|
() => {...} |
TreeifierNodeTypes.function | function |
arrow functions |
function (...) {...} |
TreeifierNodeTypes.function | function |
standard functions and methods |
Symbol( "atari" ) |
TreeifierNodeTypes.symbol | Symbol(atari) |
object Symbols (typescript) |
[1,2,3] |
TreeifierNodeTypes.array | [1, 2, 3] |
array containing a single type of items |
["a", 1, null, { objectID: 123 } ] |
TreeifierNodeTypes.array | [a, 1, , [object Object]](to be improved!) |
array containing mixed value types |
{} |
TreeifierNodeTypes.emptyObject | {} |
a real object! it's not the same as the "empty" type above |
{ ID: 123, name: "foo" } |
TreeifierNodeTypes.nonEmptyObject | do not use toString() on a branch node | a real object! This object contains data i.e. it's a "branch"! |
[ { a: 1 }, { }, { c: 3 } ] |
TreeifierNodeTypes.arrayOfObjects | do not use toString() on a branch node | this array of "real objects" is parsed as a "branch", each contained object is a sub tree. |
Note: the nodeType value TreeifierNodeTypes.unknown is defined as well but should never popup i.e. should never be assigned to a TreeifierNode. Otherwise, please file a Bug in the GitHub repository, Thanks!
Here's an example object and its representation
This type define the shape of a processor function (callback function) that the treeifier engine will call for each and every node of the generated TreeifierNode structure.
nodeargument: the current node for which the processor function should create a representation.return value: the representaion of the current node is to be returned to the caller of the processor function.
Well... this section is still "to-be-documented". In the mean time, please have a look at the sources.
Please see the procesor function documentation.