ug

    0.0.8 • Public • Published

    UnitGraph

    Build Status

    UnitGraph is a simple Graph traversal library for io.js. It is intended for quick, synchronous in-memory traversals including route tracing and finding closest nodes to a target.

    Installation

    UnitGraph is available via npm. Simply run npm install ug and then:

    let ug = require('ug');

    To use the package. :)

    Examples

    Find all nodes of type 'person' with name matching 'ae'

    let ug = require('ug');
    let graph = new ug.Graph();
     
    graph.createNode('person', {name: 'Rachael'});
    graph.createNode('person', {name: 'Stephanie'});
    graph.createNode('person', {name: 'Michael'});
    graph.createNode('person', {name: 'Donovan'});
     
    graph.nodes('person').query().filter({name__ilike: 'ae'}).units();
     
    // [ Node (person {name: Rachael}), Node (person {name: Michael}) ]

    Find the shortest path between two nodes

    let ug = require('ug');
    let graph = new ug.Graph();
     
    let civilian = graph.createNode('person', {name: 'Clark Kent'});
    let superman = graph.createNode('superhero', {name: 'Superman'});
    graph.createEdge('wears_glasses').link(superman, civilian);
     
    graph.trace(
      graph.nodes('person').query().filter({name: 'Clark Kent'}).first(),
      graph.nodes('superhero').query().filter({name: 'Superman'}).first()
    );
    // Path: Node (person {name: "Clark Kent"}) << Edge (wears_glasses {}) << Node (superhero {name: 'Superman'})

    Find all closest nodes, ordered by distance, of a certain type

    let ug = require('ug');
    let graph = new ug.Graph();
     
    let classification = graph.createNode('classification', {name: 'Sharing Economy'});
     
    let corps = {
      uber: graph.createNode('corporation', {name: 'Uber'}),
      storefront: graph.createNode('corporation', {name: 'Storefront'}),
      airbnb: graph.createNode('corporation', {name: 'AirBnB'})
    };
     
    let industries = {
      vc: graph.createNode('industry', {name: 'Venture Capital'}),
      hospitality: graph.createNode('industry', {name: 'Hospitality'}),
      taxi: graph.createNode('industry', {name: 'Taxi'})
    };
     
    graph.createEdge('business_model').link(corps.uber, classification);
    graph.createEdge('business_model').link(corps.airbnb, classification);
    graph.createEdge('business_model').link(corps.storefront, classification);
    graph.createEdge('emotion', {type: 'happy'}).link(industries.vc, classification);
    graph.createEdge('emotion', {type: 'sad'}).link(industries.hospitality, classification);
    graph.createEdge('emotion', {type: 'sad'}).link(industries.taxi, classification);
     
    graph.closest(
      graph.nodes('classification').query().first(), // grab Sharing Economy node
      {
        compare: function(node) {
          // forget industries and uber!
          return node.entity !== 'industry' && node.get('name') !== 'Uber';
        },
        direction: -1 // only track nodes that feed in to this one
      }
    );
     
    // returns two paths, one from Sharing Economy << (business_model) << AirBnB
    //    and Sharing Economy << business_model << Storefront,
    //    ordered by their distance

    Documentation

    Graph

    javascript Graph()

    
    Constructor. Part of the `ug` namespace. Use with `new` keyword, i.e.
    
    ```javascript
    let Graph = require('ug').Graph;
    let graph = new Graph();
    

    Graph#unit

    unit( [Number] uniqid )
      returns [Unit] ([Node] or [Edge])
    

    Grabs a unit (node or edge) by their unique id (automatically assigned by their parent Graph object).

    Graph#nodeCount

    nodeCount()
      returns [Number]
    

    Returns the total number of nodes that belong to the graph.

    Graph#edgeCount

    edgeCount()
      returns [Number]
    

    Returns the total number of edges that belong to the graph.

    Graph#createNode

    createNode( [String] entity, [Object] properties )
      returns [Node]
    

    Creates a node belonging to the parent graph, with entity type entity and calls Unit#load to attach properties to the node.

    Automatically creates a NodeCollection of type entity belonging to the parent graph if one does not yet exist.

    Graph#createEdge

    createEdge( [String] entity, [Object] properties )
      returns [Edge]
    

    Creates an edge belonging to the parent graph, with entity type entity and calls Unit#load to attach properties to the edge.

    Automatically creates an EdgeCollection of type entity belonging to the parent graph if one does not yet exist.

    Graph#nodes

    nodes( [String] entity )
      returns [NodeCollection]
    

    Returns the parent graph's NodeCollection object of the specified entity. Invoking this method will create a NodeCollection if one does not yet exist.

    Graph#edges

    edges( [String] entity )
      returns [EdgeCollection]
    

    Returns the parent graph's EdgeCollection object of the specified entity. Invoking this method will create a EdgeCollection if one does not yet exist.

    Graph#trace

    trace( [Node] fromNode, [Node] toNode, [Number] direction )
      returns [Path]
    

    Finds the shortest distance Path from fromNode to toNode. If there are multiple paths of the same distance, it will return the first one it finds.

    direction can be -1 (incoming nodes only), 0 (doesn't matter) or 1 (outgoing nodes only).

    You should not depend on this method to always return the same Path.

    For finding all paths of a specific distance, use Graph#closest.

    Graph#closest

    closest( [Node] node, [Object] options )
      returns [Array] of [Path]
    

    Finds all closest nodes to node and returns their Paths in an array, ordered by total distance. Nodes are filtered based on the parameters passed in options.

    These include:

    options.compare: A function containing a comparison constraint for the node.

    Should return true for an inclusion of the target node, and false to ignore it.

    Example:

    let options = {
      compare: function(node) {
        return node.entity === 'person';
      }
    }

    This will make sure only nodes with the entity 'person' are included in your results.

    options.count: A number indicating the amount of results to return. 0 will return all results.

    options.direction: Which direction can we traverse the graph in? Can be -1 (incoming nodes only), 0 (doesn't matter) or 1 (outgoing nodes only).

    options.minDepth: The minimum distance from our target at which to start counting nodes in our result set.

    options.maxDepth: The maximum distance from our target at which we can finish counting nodes in our result set.

    Graph#toJSON

    toJSON()
      returns [String]
    

    Creates a JSON string representation of our graph using the toJSON of graph consituents.

    Graph#fromJSON

    fromJSON( [String] json )
      returns [self: Graph]
    

    Synchronously prepares a graph from a json string representation.

    Graph#save

    save( [String] filename, [Function] callback )
      returns [self: Graph]
    

    Save the current graph to a file, asynchronously. Specify full path in filename.

    callback is of the form function(err) {}.

    Graph#load

    load( [String] filename, [Function] callback )
      returns [self: Graph]
    

    Load the current graph to a file, asynchronously, from filename.

    callback is of the form function(err) {}.


    Unit

    Unit()
    

    Inaccessible constructor. Base prototype for Node and Edge.

    Unit#load

    load( [Object] properties )
      returns [self: Unit]
    

    Load all properties for the Unit from properties. Creates a shallow copy of the object provided.

    Unit#set

    set( [String] property, [Any] value )
      returns [Any]
    

    Set a specific property of the Unit. Returns the set property value.

    Unit#unset

    unset( [String] property )
      returns [Boolean]
    

    Unsets property of the Unit. Returns true on success, false on failure.

    Unit#has

    has( [String] property )
      returns [Boolean]
    

    Returns true if Unit has property property, otherwise returns false.

    Unit#get

    get( [String] property )
      returns [Any]
    

    Returns the associated property value of Unit.

    Unit#toString

    toString()
      returns [String]
    

    Returns a string representation of the Unit.

    Unit#valueOf

    valueOf()
      returns [String]
    

    See: Unit#toString.


    Node

    Node()
      extends [Unit]
    

    Inaccessible constructor. Inherits from Unit.

    Use Graph#createNode to invoke this constructor.

    Node#unlink

    unlink()
      returns true
    

    De-references all connected edges from itself, and itself from all connected edges.


    Edge

    Edge()
      extends [Unit]
    

    Inaccessible constructor. Inherits from Unit.

    Use Graph#createEdge to invoke this constructor.

    Edge#link

    link( [Node] fromNode, [Node] toNode, [Boolean] duplex )
      returns [self: Edge]
    

    Links two nodes directionally (fromNode to toNode) or bi-directionally if duplex is set to true.

    Edge#unlink

    unlink()
      returns true
    

    De-references both connected nodes from itself, and itself from both connected nodes.

    Edge#setDistance

    setDistance( [Number] distance )
      returns [self: Edge]
    

    Sets the distance (length) of the edge.

    Edge#setWeight

    setWeight( [Number] weight )
      returns [self: Edge]
    

    Sets the distance (length) of the edge to 1 / weight.

    Edge#oppositeNode

    oppositeNode( [Node] node )
      returns [Node]
    

    Returns the node opposite to the one provided (if provided node is connected to the edge). Otherwise returns undefined.


    Collection

    Collection()
    

    Inaccessible constructor. Base prototype for NodeCollection and EdgeCollection.

    Collection#name

    name()
      returns [String]
    

    Returns the entity name of the collection.

    Collection#indices

    indices()
      returns [Array] of [String]
    

    Provides an array of all indexed fields in the collection

    Collection#createIndex

    createIndex( [String] field )
      returns [self: Collection]
    

    Adds field as an index on the collection. Useful for Collection#find and Collection#destroy.

    Collection#createIndices

    createIndex( [Array] fieldList )
      returns [self: Collection]
    

    Adds each fieldList entry as an index on the collection. Useful for Collection#find and Collection#destroy.

    Collection#find

    find( [String or Number] id )
    find( [String] index, [String or Number] id )
      returns [Unit] ([Node or Edge])
    

    Returns the Unit (node or edge) associated with the supplied index and id.

    If no index is provided, it will use the first index added to the Collection.

    Collection#destroy

    destroy( [String or Number] id )
    destroy( [String] index, [String or Number] id )
      returns [Unit] ([Node or Edge])
    

    Removes the Unit (node or edge) associated with the supplied index and id from the collection and returns it.

    If no index is provided, it will use the first index added to the Collection.

    Collection#query

    query()
      returns [Query]
    

    Creates a new Query object with all units in the collection.


    NodeCollection

    NodeCollection()
      extends [Collection]
    

    Inaccessible constructor. Inherits from Collection.

    Use Graph#nodes(entity) to invoke this constructor automatically.


    EdgeCollection

    EdgeCollection()
      extends [Collection]
    

    Inaccessible constructor. Inherits from Collection.

    Use Graph#edges(entity) to invoke this constructor automatically.


    Query

    Query()
      extends [Collection]
    

    Inaccessible constructor. Inherits from Collection.

    Use Collection#query to instantiate this object.

    Query#filter

    filter( [Array] filtersObjects )
    filter( [Object] filters_1, ..., [Object] filters_n )
      returns [Query]
    

    Returns a Query object containing a subset of units that has been filtered based on supplied filtersObjects. Can be passed in as an array or separate arguments.

    See DataCollection.js examples for a better idea of how these filters work. Note: the implementations are not completely identical.

    Supported filters for UnitGraph's Query object are currently:

    is
    not
    gt
    lt
    gte
    lte
    ilike
    like
    in
    not_in
    

    Query#exclude

    exclude( [Array] filtersObjects )
    exclude( [Object] filters_1, ..., [Object] filters_n )
      returns [Query]
    

    Returns the complementary set of units when compared to Query#filter. (Excludes instead of includes filter values).

    Query#first

    first()
      returns [Unit] ([Node or Edge])
    

    Returns the first unit in the query set.

    Query#last

    last()
      returns [Unit] ([Node or Edge])
    

    Returns the last unit in the query set.

    Query#units

    units()
      returns [Array] of [Unit] ([Node or Edge])
    

    Returns all units in the query set.


    Path

    Path()
    

    Inaccessible constructor. Returned from Graph#trace and Graph#closest.

    Path#start

    start()
      returns [Node]
    

    Returns the first node in the path.

    Path#end

    end()
      returns [Node]
    

    Returns the last node in the path.

    Path#length

    length()
      returns [Number]
    

    Returns an integer indicating the number of edges in the path.

    Path#distance

    distance()
      returns [Number]
    

    Returns a number indicating the total distance of the path.

    Path#prettify

    prettify()
      returns [String]
    

    Provides a human-readable string representation of the path.

    Path#toString

    toString()
      returns [String]
    

    Alias for Path#prettify.

    About

    UnitGraph is MIT licenced, so have fun with it!

    Reach me on Twitter, @keithwhor.

    Check out my personal website keithwhor.com.

    Keywords

    none

    Install

    npm i ug

    DownloadsWeekly Downloads

    466

    Version

    0.0.8

    License

    MIT

    Last publish

    Collaborators

    • keithwhor