Class: Project

Project(projectId, storage, mainLogger, gmeConfig)

new Project(projectId, storage, mainLogger, gmeConfig)

This project uses a common storage to connect to the database on the server via web-sockets. It can run under both nodeJS and in the browser.

Parameters:
Name Type Description
projectId string

Id of project to be opened.
storage object

Storage connected to the server and database.
mainLogger object

Logger instance.
gmeConfig GmeConfig
Source:

Extends

Members

gmeConfig :GmeConfig

Type:
Inherited From:
Source:

logger :GmeLogger

Type:
Inherited From:
Source:

projectId :string

Unique ID of project, built up by the ownerId and projectName.

Type:
Inherited From:
Source:
Example
'guest+TestProject', 'organization+TestProject2'

Methods

createBranch(branchName, newHash, callbackopt) → {external:Promise}

Creates a new branch with head pointing to the provided commit hash.

Parameters:
Name Type Attributes Description
branchName string

Name of branch to create.
newHash module:Storage~CommitHash

New commit hash for branch head.
callback function <optional>

If provided no promise will be returned.

Properties
Name Type Description
error null | Error

The result of the execution.
result module:Storage~CommitResult

Status about the branch update.
Overrides:
Source:
Returns:

On success the promise will be resolved with module:Storage~CommitResult result.
On error the promise will be rejected with Error error.

Type
external:Promise

createTag(tagName, commitHash, callbackopt) → {external:Promise}

Creates a new tag pointing to the provided commit hash.

Parameters:
Name Type Attributes Description
tagName string

Name of tag to create.
commitHash module:Storage~CommitHash

Commit hash tag will point to.
callback function <optional>

If provided no promise will be returned.

Properties
Name Type Description
error null | Error

The result of the execution.
Overrides:
Source:
Returns:

On success the promise will be resolved with nothing.
On error the promise will be rejected with Error error.

Type
external:Promise

deleteBranch(branchName, oldHash, callbackopt) → {external:Promise}

Deletes the branch.

Parameters:
Name Type Attributes Description
branchName string

Name of branch to create.
oldHash module:Storage~CommitHash

Previous commit hash for branch head.
callback function <optional>

If provided no promise will be returned.

Properties
Name Type Description
error null | Error

The result of the execution.
result module:Storage~CommitResult

Status about the branch update.
Overrides:
Source:
Returns:

On success the promise will be resolved with module:Storage~CommitResult result.
On error the promise will be rejected with Error error.

Type
external:Promise

deleteTag(tagName, callbackopt) → {external:Promise}

Deletes the given tag.

Parameters:
Name Type Attributes Description
tagName string

Name of tag to delete.
callback function <optional>

If provided no promise will be returned.

Properties
Name Type Description
error null | Error

The result of the execution.
Overrides:
Source:
Returns:

On success the promise will be resolved with nothing.
On error the promise will be rejected with Error error.

Type
external:Promise

getBranchHash(branchName, callbackopt) → {external:Promise}

Retrieves the commit hash for the head of the branch.

Parameters:
Name Type Attributes Description
branchName string

Name of branch.
callback function <optional>

If provided no promise will be returned.

Properties
Name Type Description
error null | Error

The result of the execution.
commitHash module:Storage~CommitHash

The commit hash.
Overrides:
Source:
Returns:

On success the promise will be resolved with module:Storage~CommitHash commitHash.
On error the promise will be rejected with Error error.

Type
external:Promise

getBranches(callbackopt) → {external:Promise}

Retrieves all branches and their current heads within the project.

Parameters:
Name Type Attributes Description
callback function <optional>

If provided no promise will be returned.

Properties
Name Type Description
error null | Error

The result of the execution.
branches Object.<string, module:Storage~CommitHash>

An object with branch names as keys and their commit-hashes as values.
Overrides:
Source:
Returns:

On success the promise will be resolved with Object.<string, module:Storage~CommitHash> branches.
On error the promise will be rejected with Error error.

Type
external:Promise

getCommitObject(branchNameOrCommitHash, callbackopt) → {external:Promise}

Retrieves the commit-object at the provided branch or commit-hash.

Parameters:
Name Type Attributes Description
branchNameOrCommitHash string

Name of branch or a commit-hash.
callback function <optional>

If provided no promise will be returned.

Properties
Name Type Description
error null | Error

The result of the execution.
commit module:Storage~CommitObject

The commit-object.
Inherited From:
Source:
Returns:

On success the promise will be resolved with module:Storage~CommitObject commitObject.
On error the promise will be rejected with Error error.

Type
external:Promise

getCommits(before, number, callbackopt) → {external:Promise}

Retrieves and array of the latest (sorted by timestamp) commits for the project. If timestamp is given it will get number of commits strictly before before. If commit hash is specified that commit will be included too.
N.B. due to slight time differences on different machines, ancestors may be returned before their descendants. Unless looking for 'headless' commits 'getHistory' is the preferred method.

Parameters:
Name Type Attributes Description
before number | module:Storage~CommitHash

Timestamp or commitHash to load history from.
number number

Number of commits to load.
callback function <optional>

If provided no promise will be returned.

Properties
Name Type Description
error null | Error

The result of the execution.
commits Array.<module:Storage~CommitObject>

The commits that match the input, ordered by their time of insertion.
Overrides:
Source:
Returns:

On success the promise will be resolved with Array.<module:Storage~CommitObject> commits.
On error the promise will be rejected with Error error.

Type
external:Promise

getCommonAncestorCommit(commitA, commitB, callbackopt) → {external:Promise}

Retrieves the common ancestor of two commits. If no ancestor exists it will result in an error.

Parameters:
Name Type Attributes Description
commitA module:Storage~CommitHash

Commit hash.
commitB module:Storage~CommitHash

Commit hash.
callback function <optional>

If provided no promise will be returned.

Properties
Name Type Description
error null | Error

The result of the execution (will be non-null if e.g. the commits do not exist or have no common ancestor).
commitHash module:Storage~CommitHash

The commit hash of the common ancestor.
Overrides:
Source:
Returns:

On success the promise will be resolved with module:Storage~CommitHash commitHash.
On error the promise will be rejected with Error error.

Type
external:Promise

getHistory(start, number, callbackopt) → {external:Promise}

Retrieves an array of commits starting from a branch(es) and/or commitHash(es).
The result is ordered by the rules (applied in order)
1. Descendants are always returned before their ancestors.
2. By their timestamp.

Parameters:
Name Type Attributes Description
start string | module:Storage~CommitHash | Array.<string> | Array.<module:Storage~CommitHash>

Branch name, commit hash or array of these.
number number

Number of commits to load.
callback function <optional>

If provided no promise will be returned.

Properties
Name Type Description
error null | Error

The result of the execution.
commits Array.<module:Storage~CommitObject>

The commits that match the input ordered as explained.
Overrides:
Source:
Returns:

On success the promise will be resolved with Array.<module:Storage~CommitObject> commits.
On error the promise will be rejected with Error error.

Type
external:Promise

getProjectInfo(callbackopt) → {external:Promise}

Retrieves the metadata of the project.

Parameters:
Name Type Attributes Description
callback function <optional>

If provided no promise will be returned.

Properties
Name Type Description
error null | Error

The result of the execution.
projectInfo object

An object with info about the project.
Overrides:
Source:
Returns:

On success the promise will be resolved with {object} projectInfo.
On error the promise will be rejected with Error error.

Type
external:Promise
Example
{
 _id: 'guest+example',
 owner: 'guest',
 name: 'example',
 info: {
     createdAt: '2016-12-02T17:52:25.029Z',
     viewedAt: '2017-01-30T22:45:15.269Z',
     modifiedAt: '2017-01-20T00:15:34.593Z',
     creator: 'guest',
     viewer: 'guest',
     modifier': 'guest'
 },
 hooks: {
     ConstraintCheckerHook': {
         url: 'http://127.0.0.1:8080/ConstraintCheckerHook',
         description': 'Checks if there are any meta violations in the project',
         events: ['COMMIT'],
         active: true,
         createdAt: '2017-01-19T23:22:46.834Z',
         updatedAt: '2017-01-19T23:22:46.834Z'
     }
 },
 rights: {
     read: true,
     write: true,
     delete: true
 },
 branches: {
     b1: '#998067142c7ff8067cd0c04a0ec4ef80d865606c',
     master: '#36df6f8c17b2ccf4e35a2a75b1e0adb928f82a61'
 }
}

getRootHash(branchNameOrCommitHash, callbackopt) → {external:Promise}

Retrieves the root hash at the provided branch or commit-hash.

Parameters:
Name Type Attributes Description
branchNameOrCommitHash string

Name of branch or a commit-hash.
callback function <optional>

If provided no promise will be returned.

Properties
Name Type Description
error null | Error

The result of the execution.
rootHash module:Core~ObjectHash

The root hash.
Inherited From:
Source:
Returns:

On success the promise will be resolved with module:Core~ObjectHash rootHash.
On error the promise will be rejected with Error error.

Type
external:Promise

getTags(callbackopt) → {external:Promise}

Retrieves all tags and their commits hashes within the project.

Parameters:
Name Type Attributes Description
callback function <optional>

If provided no promise will be returned.

Properties
Name Type Description
error null | Error

The result of the execution.
tags Object.<string, module:Storage~CommitHash>

An object with tag names as keys and their commit-hashes as values.
Overrides:
Source:
Returns:

On success the promise will be resolved with Object.<string, module:Storage~CommitHash> tags.
On error the promise will be rejected with Error error.

Type
external:Promise

getUserId() → {string}

Return the identity of the current user of this project.

Overrides:
Source:
Returns:

the userId

Type
string

makeCommit(branchName, parents, rootHash, coreObjects, msg, callbackopt) → {external:Promise}

Makes a commit to data base. Based on the root hash and commit message a new module:Storage.CommitObject (with returned hash) is generated and insert together with the core objects to the database on the server.

Parameters:
Name Type Attributes Default Description
branchName string

Name of branch to update (none if null).
parents Array.<module:Storage~CommitHash>

Parent commit hashes.
rootHash module:Core~ObjectHash

Hash of root object.
coreObjects module:Core~DataObject

Core objects associated with the commit.
msg string 'n/a'

Commit message.
callback function <optional>

If provided no promise will be returned.

Properties
Name Type Description
error null | Error

The result of the execution.
result module:Storage~CommitResult

Status about the commit and branch update.
Overrides:
Source:
Returns:

On success the promise will be resolved with module:Storage~CommitResult result.
On error the promise will be rejected with {Error} error.

Type
external:Promise
Examples
var persisted = core.persist(rootNode);

project.makeCommit('master', ['#thePreviousCommitHash'], persisted.rootHash, persisted.objects, 'new commit')
  .then(function (result) {
    // result = {
    //   status: 'SYNCED',
    //   hash: '#thisCommitHash'
    // }
  })
  .catch(function (error) {
    // error.message = 'Not authorized to read project: guest+project'
  });
project.makeCommit('master', ['#notPreviousCommitHash'], persisted.rootHash, persisted.objects, 'new commit')
  .then(function (result) {
    // result = {
    //   status: 'FORKED',
    //   hash: '#thisCommitHash'
    // }
  })...
project.makeCommit(null, ['#anExistingCommitHash'], persisted.rootHash, persisted.objects, 'new commit')
  .then(function (result) {
    // result = {
    //   hash: '#thisCommitHash'
    // }
  })...
project.makeCommit('master', ['#aPreviousCommitHash'], previousRootHash, {}, 'adding a commit to master')
  .then(function (result) {
    // result = {
    //   status: 'SYNCED',
    //   hash: '#thisCommitHash'
    // }
  })...

sendDocumentOperation(data)

Send operation made, and optionally selection, on document at docId.

Parameters:
Name Type Description
data object
Properties
Name Type Attributes Description
docId string
operation ot.TextOperation
selection ot.Selection <optional>
Source:

sendDocumentSelection(data)

Send selection on document at docId. (Will only be transmitted if client is Synchronized.)

Parameters:
Name Type Description
data object
Properties
Name Type Description
docId string
selection ot.Selection
Source:

setBranchHash(branchName, newHash, oldHash, callbackopt) → {external:Promise}

Updates the head of the branch.

Parameters:
Name Type Attributes Description
branchName string

Name of branch to update.
newHash module:Storage~CommitHash

New commit hash for branch head.
oldHash module:Storage~CommitHash

Current state of the branch head inside the database.
callback function <optional>

If provided no promise will be returned.

Properties
Name Type Description
error null | Error

The result of the execution.
result module:Storage~CommitResult

Status about the branch update.
Overrides:
Source:
Returns:

On success the promise will be resolved with module:Storage~CommitResult result.
On error the promise will be rejected with Error error.

Type
external:Promise

unwatchDocument(data, callbackopt) → {Promise}

Stop watching the document.

Parameters:
Name Type Attributes Description
data object
Properties
Name Type Attributes Description
docId string

document id, if not provided branchName, nodeId, attrName must be.
branchName string <optional>
nodeId string <optional>
attrName string <optional>
callback function <optional>
Properties
Name Type Description
err Error | null

If failed to unwatch the document
Source:
Returns:
Type
Promise

watchDocument(data, atOperation, atSelection, callbackopt) → {Promise}

Start watching the document at the provided context.

Parameters:
Name Type Attributes Description
data object
Properties
Name Type Description
branchName string
nodeId string
attrName string
attrValue string

If the first client entering the document the value will be used
atOperation function

Triggered when other clients' operations were applied

Properties
Name Type Description
operation ot.Operation

Triggered when other clients made changes
atSelection function

Triggered when other clients send their selection info

Properties
Name Type Description
data object
Properties
Name Type Description
selection ot.Selection | null

null is passed when other client leaves
userId string

name/id of other user
socketId string

unique id of other user
callback function <optional>
Properties
Name Type Description
err Error | null

If failed to watch the document
data object
Properties
Name Type Description
docId string

Id of document
document string

Current document on server
revision number

Revision at server when connecting
users object

Users that were connected when connecting
Source:
Returns:
Type
Promise