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 |
Extends
Members
-
gmeConfig :GmeConfig
-
Type:
- Inherited From:
-
logger :GmeLogger
-
Type:
- Inherited From:
-
projectId :string
-
Unique ID of project, built up by the ownerId and projectName.
Type:
- Inherited From:
Example
'guest+TestProject', 'organization+TestProject2'
Methods
-
createBranch(branchName, newHash [, callback])
-
Creates a new branch with head pointing to the provided commit hash.
Parameters:
Name Type Argument 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.
- Inherited From:
- Overrides:
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 [, callback])
-
Creates a new tag pointing to the provided commit hash.
Parameters:
Name Type Argument 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.
- Inherited From:
- Overrides:
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 [, callback])
-
Deletes the branch.
Parameters:
Name Type Argument 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.
- Inherited From:
- Overrides:
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 [, callback])
-
Deletes the given tag.
Parameters:
Name Type Argument 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.
- Inherited From:
- Overrides:
Returns:
On success the promise will be resolved with nothing.
On error the promise will be rejected with Error error.- Type
- external:Promise
-
getBranches( [callback])
-
Retrieves all branches and their current heads within the project.
Parameters:
Name Type Argument 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.
- Inherited From:
- Overrides:
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
-
getBranchHash(branchName [, callback])
-
Retrieves the commit hash for the head of the branch.
Parameters:
Name Type Argument 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.
- Inherited From:
- Overrides:
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
-
getCommitObject(branchNameOrCommitHash [, callback])
-
Retrieves the commit-object at the provided branch or commit-hash.
Parameters:
Name Type Argument 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:
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 [, callback])
-
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 Argument 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.
- Inherited From:
- Overrides:
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 [, callback])
-
Retrieves the common ancestor of two commits. If no ancestor exists it will result in an error.
Parameters:
Name Type Argument 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.
- Inherited From:
- Overrides:
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 [, callback])
-
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 Argument 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.
- Inherited From:
- Overrides:
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( [callback])
-
Retrieves the metadata of the project.
Parameters:
Name Type Argument 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.
- Inherited From:
- Overrides:
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 [, callback])
-
Retrieves the root hash at the provided branch or commit-hash.
Parameters:
Name Type Argument 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:
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( [callback])
-
Retrieves all tags and their commits hashes within the project.
Parameters:
Name Type Argument 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.
- Inherited From:
- Overrides:
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()
-
Return the identity of the current user of this project.
- Inherited From:
- Overrides:
Returns:
the userId
- Type
- string
-
makeCommit(branchName, parents, rootHash, coreObjects, msg [, callback])
-
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 Argument 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.
- Inherited From:
- Overrides:
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 Argument Description docId
string operation
ot.TextOperation selection
ot.Selection <optional>
-
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 -
setBranchHash(branchName, newHash, oldHash [, callback])
-
Updates the head of the branch.
Parameters:
Name Type Argument 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.
- Inherited From:
- Overrides:
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 [, callback])
-
Stop watching the document.
Parameters:
Name Type Argument Description data
object Properties
Name Type Argument 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
Returns:
- Type
- Promise
-
watchDocument(data, atOperation, atSelection [, callback])
-
Start watching the document at the provided context.
Parameters:
Name Type Argument 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
Returns:
- Type
- Promise