Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »


8.5.0 • Public • Published


NPM version NPM downloads Code coverage Build status Dependencies

NPM info

Weaver SDK for JavaScript

A library that gives you access to the Weaver platform from your JavaScript app.

Getting started



npm i -S weaver-sdk

Create the instance

Weaver = require('weaver-sdk')
weaver = new Weaver()

Be sure to only create a single Weaver instance. If you need to get a reference to a previously instantiated Weaver instance later, or within devtools, just do:

weaver = Weaver.getInstance()

Connect to a running weaver-server


Sign in with an existing user account for your weaver-server (or admin : admin if you've just cloned a weaver-server and there are no accounts yet)


Select or create a new Project

# select an existing project 
# .. or create 
= new Weaver.Project(projectNameprojectId)
p.create() # Required. Spins up a new database on weaver-server, which will forevermore be linked with this Weaver.Project 

You have now:

  • Instantiated weaver
  • Connected to a running server
  • Signed-in with a valid user account
  • Selected a project to work on

You're ready to start creating and interacting with nodes.


# creates a node (only client side for now) 
= new Weaver.Node('hello-weaver')
# -> 'hello-weaver' 
# set a name attribute 
n.set('name''The First Node')
# -> 'The First Node' 
# create a relation 
= new Weaver.Node('how-are-you-weaver')
o.set('name''The Second Node')
# getting relations 
# this returns a Weaver.RelationNode, which has a bunch of properties, among them a 'nodes' array, which contains all the nodes which are linked from the node 'n' via the relation 'hasDescendant' 
# -> returns the first relation for this relation key, in this case, the Weaver.Node object referenced by o 
# gets the name attribute of the first relation from 'n' for the relation key 'hasDescendant' 
# -> 'The Second Node' 
# saving to db
# this collects all the pending writes on the node n, and pushes them to the database. 

In our example, calling will execute several write operations on the database:

  • a create node operation for node n
  • a create attribute operation for the name attribute we set for n
  • a create relation operation for node n to node o, using the relation key hasDescendant

In addition, is downwards recursive, so it will collect and execute all pending writes on all relations of n, and all relations of those nodes, etc. So, calling in our example above, will also collect and execute the pending write operations on node o:

  • a create node operation for node o
  • a create attribute operation for the name attribute we set for o

, as o is a relation of n. Pretty sweet, right?

# loading saved nodes from the database 
# -> 'The First Node' 
  # nodes are loaded with a depth/eagerness of 1 
  # relations will therefore need to be loaded explicitly 
    # -> undefined 
    # -> 'The Second Node' 

Reference API


Class Methods

  # return the weaver instance 
  # set's the Weaver.Model to be used by default 
  # returns the current default model 
  # Shout a message to other connected clients 
  # Listen to shouted messages and perform the supplied callback 
  # Listen perform the supplied callback when events of the provided type are published to the server 
  subscription = Weaver.subscribe('node.created'(msg, node) ->
    if is 'hello-world'
      console.log 'hello-weaver'
  new Weaver.Node('hello-world')
  # -> 'hello-weaver' 
  # Unsubscribe from a specific subscription 
  # Unsubscribe from all subscriptions 

Instance methods

  # returns sdk version 
  # logs version of connected server 
  # sets endpoint of weaver-server to connect to 
  # breaks connection with weaver-server, if connected to one 
  # sets current project to read from/write to 
  # returns the current project 
  # signs out the current user 
  # returns the currently signed-in user 
  # retrieves a user token, and a user object. 
  # signs in a user using a token retrieved from the server 
  # wipes: 
  #   - all projects on the server 
  #   - all user data on the server 


Class methods

  new Weaver.Node(nodeIdgraph)
  # creates a new Weaver.Node, don't forget to call `save` to persist to db 
  # returns a Promise which will resolve the specified node if it exists 
  # creates a shallow Node with the specified id 
  # note: does not create a create.node operation in pendingWrites, so will not push a node creation operation to the server. 
  # not recommended unless you know what you're doing, use Weaver.Node.load instead 
  # gets the node matching the id if it exists, or constructs a new node with the specified id 
  # pass an array of nodes with pendingWrites to save them all at once with a single server transaction 
  # pass an array of nodes to destroy them all at once with a single server transaction 

Instance methods

  # same as Weaver.Node.load(
  # returns the id of a node 
  # returns a map of loaded attributes on this node 
  # returns a map of loaded relations on this node 
  # sets an attribute on the node 
  # unsets an attribute on the node 
  # gets the value for a given attribute key on the node 
  # returns a Weaver.Relation for the given relation key 
  # note, creates an empty Weaver.Relation object if no loaded relation are found. 
  # clones a node. 
  # recursively clones relations of the node if relationsToTraverse is defined 
  # checks if the supplied node refers to the same node as the instance from a database perspective (id comparison)
  # executes all pending db writes on the instance 
  # is recursively called on all loaded relations of this node 
  # destroys the instance, also on the db 


Instance methods

  # loads all nodes on this relation, so they will no longer be shallow
  # returns the relationNode linking to the passed node, or throws an error if no relationNode is present linking to the passed node 
  # returns all nodes linked to with the current relation key 
  # returns the first node linked to with the current relation key 
  # links to the passed node from the instance relation 
  # unlinks the passed node from the relation instance 


Class methods

  # Lists all projects on the server that the logged in user has access to. 

Instance Methods

  new Weaver.Project(@name@projectId)
  # creates a new Weaver.Project clientside 
  # Publishes a create-project operation on the server. 
  # Consider this as the persistent constructor 
  # Self-explanatory. This is a persisting operation. 
  # Wipes all data from this project, without deleting the project itself 
  # Freezes project in it's current state, preventing any further writing 
  # Unfreezes project, allowing writing as normal 
  # Return's the frozen state of this project 
  # Renames this project on the server 
  # Clone's this project in it's entirety 
  # Returns a snapshot of this project, defaults to zipped = false, shouldBeJson = true 
  # Clone's this project in it's entirety 
  # Add some meta data to this project relating to a specific app 
  # Removes some meta data from this project relating to a specific app 
  # Returns a map which contains metadata for each app relating to this project, keyed by the app's name 


Class Methods

  # create a shallow Weaver.User with aupplied userToken set 
  # lists all users on the server 
  # lists all users with access to the current project 

Instance Methods
  # Returns the userId for the User instance
  # Persists user data to server 
  # Changes a user's password 
  # Saves the user and signs in as currentUser 
  # Destroys the user 
  # Returns the projects a user has access to 


Class methods

  # Fires the callback whenever a query is resolved. 
  # The callback is passed one argument, which contains information about the query which was just resolved 
  # Destroys any notifiers which were created 

Instance methods

  # Executes the query and returns results constructed with the supplied Constructor, if one is given 
  # Executes the query and returns a count of the results 
  # Executes the query and returns the first result 
  # Limits the amount of results (default/maximum permitted is 1,000) 
  # Skips the passed amount of results. Useful for Result pagination 
  # Orders results based on their value for a given attribute key 
Exclusion Criteria
  # Adds a restriction on the query based on the ids of the array of passed nodes. (an array of ids is acceptable here too) 
  # Restricts based on attributes. Results must match the passed key : value args 
  # Restricts based on attributes. Results must not match the passed key : value args 
  # Restricts based on attributes. Results must have a value which matches the passed key, and which value matches the rule described. 
  # These all restrict based on attributes. The attribute value must respect the mathematical rule described 
  # These restrict based on incoming relations. key is the relation key, and node is the node which the relation must originate from. node is an optional argument here, if node is not passed, then this criteria is considered passed if ANY relation exists for the passed key. 
  # Same as above, but for outgoing relations instead 
Extra loading instructions
  # Will fully load outgoing relations with a relation key matching any one of the passed arguments 
  # As above, but will recursively load 
  # Will fully load incoming relations with a relation key matching any one of the passed arguments. 
  # The incoming relations become part of the _relationsIn_ member of the 
  # loaded nodes. 
  # If multiple relationKeys are specified in the same call, it will follow 
  # path along incoming relations. so a call with ('key1', 'key2') will load 
  # nodes with a 'key1' relation to a query result node, and then nodes with 
  # a 'key2' relation to the additionally loaded nodes. Nodes with a 'key2' 
  # relation to the original result node will not be loaded. 
  # To load nodes with different relations in to a query result node, use 
  # multiple selectIn calls.
  # Will restrict the attributes of loaded nodes to those specified 
  # Will restrict the relations of loaded nodes to those specified 
Nesting queries / FOAF

Any query which contains a node as an argument may instead be passed a nested query.

  new Weaver.Query().hasRelationOut('hasChild',
    new Weaver.Query().hasRelationOut('attendsSchool''*')
  # will return all nodes which have an outgoing hasChild relation to a node which has an outgoing attendsSchool relation. 


Class Methods

  # Load a Weaver.Plugin which exists on the server 
  # lists all plugins on the server 

Instance Methods

  # Prints the functions available for this plugin 
  # Returns the plugin name 
  # Returns the plugin version 
  # Returns the plugin author 
  # Returns the plugin description 



Step 1: Define a model

This will create a new Model with the name 'Man'

manModel = new Weaver.Model("Man")

This adds a new getter to any member of the 'Man' model. from now on, calling something like manMember.get('name'), will return the object of the triple manMember -> hasName -> object.


The previous example added a getter for an attribute, to add a getter for a relation, you should prefix the predicate with an '@'


Call .setStatic() on a model to set a static property for the model. Now, all members of the 'Man' model will already have the property latinName set to "Homo sapien" upon instantiation. In addition to this, the following triple will be inserted into any connected db manMember -> hasLatinName -> "Homo sapien".

     latinName: "hasLatinName"
   .setStatic("latinName", "Homo sapien")

When you've finished describing your model, call buildClass() to get a constructor to initialize new members of that model.

   Man = manModel.buildClass()
   trump = new Man()
Step 2: Instantiate a member

Model members extend Weaver.Node. They can be saved to the database, to be loaded later, and if their constructor is passed an argument, The root node of that member will be initialized with that argument as an id.

    typeModel = new Weaver.Model("Type")
    Type = typeModel.buildClass();
    manType = new Type("lib:Man")

Dynamic properties for model members can be set with .setProp(propKey, propVal). Use setProp() both for setting attributes and adding relations, the model will figure out what to do based on the structure you provided earlier.

        manType.setProp("name", "The Type node for all men.")
Step 3: Nest models to describe complex structures

Include a model member in the definition for another model.

      type: ["@hasType",]
      latinName: "hasLatinName"
    .setStatic("latinName", "Homo sapien")
    .setStatic("type", manType)

Now all man model members will be instantiated with a hasType relationship to the manType node (the one with id 'lib:Man', also the root of the manType model member).

You can even chain getters together to return deep properties of a model member.

   typeModel = new Weaver.Model("Type")
   Type = typeModel.buildClass();
   manType = new Type("lib:Man")
   manType.setProp("name", "Type node for all men")
     latinName: "hasLatinName"
     nameOfType: ""  //use a '.' to seperate path segments
   .setStatic("latinName", "Homo sapien")
   .setStatic("type", manType)
   Man = manModel.buildClass()
   trump = new Man()
   trump.setProp("name", "Donald Drumpf")
   trump.get("name")         //returns "Donald Drumpf"
   trump.get("latinName")    //returns "Homo sapien"
   trump.get("type")         //returns WeaverModelMember instance
   trump.get("")    //returns "Type node for all men"
   trump.get("nameOfType")   //returns "Type node for all men"
   trump.destroy()           //would that it were so easy..

## Creating your own plugins

Got something special that you wish your weaver-server could do? Build your own Weaver.Plugin to add server-side functionality. Define any functionality you want to offload to the server within a Weaver.Plugin, and then access it using an integrated prebuilt interface within the sdk.

We have built a weaver-service bootstrapper here to get you started, so download that, and bootstrap your new service to get started.

The directory in which you bootstrapped your service will already have generated a, but we'll explain what to do here also for ease of reference.

Let's say we made a cloud-sync service, to sync some data with a separate cloud store. First we'll install the bootstrapper: (and yeoman if you haven't already got it)

$ npm install -g yo
$ npm install -g generator-weaver-service

Then we'll run the bootstrapper:

$ yo weaver-service
# be careful not to use any capital letters in the organization name

Then we'll add some configuration to our local weaver-server instance so that it picks up our new service

# in #{weaver-server-root-folder}/config/ 
    'cloud-sync-service': 'http://localhost:2525' #or whatever port number you chose during bootstrapping 

Then, back in /cloud-sync-service

$ npm run prepublish
$ node lib/index.js

Your service should now be up-and-running! Restart your weaver-server and make sure you see some acknowledgement of your new service in the startup logs.

2018-05-31 14:06:49 | INFO | Service plugin cloud-sync-service loaded with 3 Swagger paths parsed

Use a weaver sdk to reference your new service, and start playing!

.then((cloudSync) ->

Building locally

$ git clone
$ npm i
$ npm run prepublish


$ npm test




npm i weaver-sdk

Downloadsweekly downloads






last publish


  • avatar
  • avatar
  • avatar
  • avatar
  • avatar
  • avatar
  • avatar