# Class: Project

## Project

#### 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

- ProjectInterface

### Members

#### gmeConfig :GmeConfig

  ##### Type:

  - GmeConfig
  Inherited From:
    - ProjectInterface#gmeConfig

#### logger :GmeLogger

  ##### Type:

  - GmeLogger
  Inherited From:
    - ProjectInterface#logger

#### projectId :string

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

  ##### Type:

  - string
  Inherited From:
    - ProjectInterface#projectId

  ##### 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:
    - ProjectInterface#createBranch
  Overrides:
    - ProjectInterface#createBranch

  ##### 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:
    - ProjectInterface#createTag
  Overrides:
    - ProjectInterface#createTag

  ##### 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:
    - ProjectInterface#deleteBranch
  Overrides:
    - ProjectInterface#deleteBranch

  ##### 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:
    - ProjectInterface#deleteTag
  Overrides:
    - ProjectInterface#deleteTag

  ##### 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:
    - ProjectInterface#getBranches
  Overrides:
    - ProjectInterface#getBranches

  ##### 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:
    - ProjectInterface#getBranchHash
  Overrides:
    - ProjectInterface#getBranchHash

  ##### 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:
    - ProjectInterface#getCommitObject

  ##### 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:
    - ProjectInterface#getCommits
  Overrides:
    - ProjectInterface#getCommits

  ##### 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:
    - ProjectInterface#getCommonAncestorCommit
  Overrides:
    - ProjectInterface#getCommonAncestorCommit

  ##### 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:
    - ProjectInterface#getHistory
  Overrides:
    - ProjectInterface#getHistory

  ##### 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:
    - ProjectInterface#getProjectInfo
  Overrides:
    - ProjectInterface#getProjectInfo

  ##### 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:
    - ProjectInterface#getRootHash

  ##### 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:
    - ProjectInterface#getTags
  Overrides:
    - ProjectInterface#getTags

  ##### 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:
    - ProjectInterface#getUserId
  Overrides:
    - ProjectInterface#getUserId

  ##### 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:
    - ProjectInterface#makeCommit
  Overrides:
    - ProjectInterface#makeCommit

  ##### 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:
    - ProjectInterface#setBranchHash
  Overrides:
    - ProjectInterface#setBranchHash

  ##### 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

#### Search results