takorogo v0.0.1-19

node-takorogo

Takorogo to JSON parser for Node.js

Installation

This module is installed via npm:

$ npm install takorogo

Example Usage

var takorogo = require('takorogo');
var rules = takorogo.parse('user <--[POSTED]-- :User');

Takorogo Syntax

Takorogo uses relations to maps properties to nodes determined by classes and their indices. That's all.

Relations

For example we have a tweet with embedded user object:

var tweet = {
    id: 481101713646960641
    user: {
        default_profile_image : false,
        id : 119102990,
        profile_background_image_url_https : "https://pbs.twimg.com/profile_background_images/444244318/16840333315.png",
        verified : false,
        /* ... */
    }
}

In this case we can say that tweet posted by user:

--[POSTED_BY]--> user:User 

Or that user posted a tweet:

<--[POSTED]-- user:User 

Or user and tweet has a bidirectional relationship:

<--[POSTED|POSTED_BY]--> user:User 

Where user is a property name that contains embedded object and :User is a name of a class.

You can specify what attribute will be stored in relation passing them to relation in parentheses:

--[PARTICIPATE_IN(score, wins)]--> game:Game

You can specify types for relation attributes:

--[PARTICIPATE_IN(score: Score, wins: Integer)]--> game:Game

Or even destructuring an array property:

entities.urls[] --[REFERS_TO(indices[first, last])]--> :Url

Attention. Currently only plain values are supported.

Relations resolved from keys

Sometimes your document just points to something via key. In this case you can specify how relation should be resolved.

in_reply_to_status_id_str => id_str <--[ REPLIED_WITH|REPLIED_TO ]--> in_reply_to:Tweet

In the last case => means that in_reply_to_status_id_str should be treated as an id_str key.

For compound keys you can use following syntax:

(longitude, latitude) => (x, y) --[ LOCATED ]--> location:Point

Attributes

Sometimes your document's structure doesn't fit plane key-value nature of node. In this case you can specify properties by paths:

--[CITIZEN_OF]--> place.country:Country 

If document's field doesn't match what you want to have in the target node you can rename it:

--[CITIZEN_OF]--> place.country => country:Country 

You also can assign types to attributes (user-defined classes are also supported):

def :Person {
    + firstName :String
    + dateOfBirth :Date
}        

Attention: attribute aliasing in types constraints are not supported yet.

Embedded objects

Embedded objects are stored inside the node. Mechanism depends on graph database engine.

Links (anonymous relations)

You can store unstructured embedded object as a link to node:

--> metadata

As for normal relations you can specify classes and arrays for links:

--> tweet:Tweet
--> comments:Comment[]

Indices

You can specify unique constraint:

UNIQUE(id)

Takorogo also handles compound constraints:

UNIQUE(firstName, lastName)

Classes & Types

You can refer to already defined class or type by colon notation:

UNIQUE(id:Int)
--> tweet:Tweet

In case when you have a collection of instances you can use an array syntax:

--> comments:Comment[]

Unstructured arrays are also supported:

--> things[]

Class Definition

To define class use def keyword:

def Tweet

You can specify primary key in parentheses:

def HashTag(text)

Compound indexes are also supported:

def Person(firstname, lastname)

And you can use paths to specify properties:

def Citizen(credentials.passport.number)

Sometimes your class's primary key is stored in array. For example we have a location document with unique combinations of longitude and latitude stored in array. For this cases you can write:

def Location(coordinates[longitude, latitude])

Complex Classes

You can define rules for complex classes in curly braces:

def User(passport.id) {
    --[CHILD_OF]--> father:Person
    --[REFERS_TO(indices[first, last])]--> entities.url.urls[]:Url
}

Enumerations

You can define enumeration mappers for arrays of fixed length:

def Coordinates [ longitude, latitude ]

After array items specified we can treat it as a regular document:

def VendorCoordinates [ longitude, latitude, vendor ] {
  UNIQUE(longitude, latitude, vendor.id)
  --[PRODUCED_BY]--> vendor:Vendor  
}

Inline Class Definition

Simple classes can be defined inside relation rules by appending class name with parentheses:

--[POPULATED_WITH]--> comment:Comment(id)

You can specify indices as in normal declaration:

--[REFERS_TO]--> urls:Url(url)[]

That will create a class Url with url as primary key and use it as a map for related nodes.

Comments

Takorogo supports only one line comments (both # and //):

# JIRA task 
def Task {
  UNIQUE(id)  // Primary key
  --[BLOCKED_BY]-->blocker:Task
}

Examples

The following Takorogo script describes tweet structure from Twitter Stream API:

# The whole tweet document returned by Twitter Stream API
def Tweet {
    UNIQUE(id_str:String)
    UNIQUE(id:Int)
    
    + location: String

    <--[POSTED]-- user:User
    --> metadata
    <--[ REPLIED_WITH|REPLIED_TO ]--> in_reply_to_status_id_str => in_reply_to:Tweet
     --[ REFERS_TO(indices[first, last]) ]--> entities.urls[]:Url
     --[ HAS_TAG(indices[first, last]) ]--> entities.hashtags[]:HashTag(text)
     --[ AT ]--> coordinates:Location
     --[ ON ]--> geo:Location
     --[ PLACED ]--> place:Place
}

# Just a point
def Coordinates [ longitude, latitude ] {
  UNIQUE(longitude: Double, latitude: Double)
}

def Location(coordinates:Coordinates)  // Simply a wrapper for coordinates 

def Place {
    --[ BOUNDED_BY ]--> bounding_box.coordinates => bounding_box:Coordinates[]
}

def User(id_str) {
    --[REFERS_TO(indices[first, last])]--> entities.url.urls[]:Url
}

Browser

Client versions of node-takorogo can be built from sources or can be found in ./client/ directory of NPM module.

Contribution

You can start from API docs.

I will accept only changes covered by unit tests.

Road map

Support indentation for class rules

def :Person
    UNIQUE(passport.id)
    --[CHILD_OF]--> father:Person

Add attribute rewrite in type constraint statements

def :Person {
    + name.first => firstName :String
}