Classes

Association

Associations are used by components to access related store documents that are linked in a document. They are also responsible for building the QueryDefinition that is used by the client to automatically fetch relationship data.

Hydrated documents used by components come with Association instances.

HasMany

Related documents are stored in the relationships attribute of the object, following the JSON API spec.

Responsible for

  • Creating relationships
  • Removing relationships
HasManyInPlace

Used when related documents are stored directly under the attribute with only the ids.

HasManyTriggersHasMany

Association used for konnectors to retrieve all their related triggers.

CozyClient

Responsible for

  • Creating observable queries
  • Hydration
  • Creating plan for saving documents
  • Associations
QueryDefinition

Chainable API to create query definitions to retrieve documents from a Cozy. QueryDefinitions are sent to links.

Schema

Stores information on a particular doctype.

  • Attribute validation
  • Relationship access
const schema = new Schema({
  todos: {
    attributes: {
      label: {
        unique: true
      }
    },
    relationships: {
      author: 'has-one-in-place'
    }
  }
}, cozyStackClient)

Functions

withClient(Component)function

HOC to provide client from context as prop

queryConnect(querySpecs)function

HOC creator to connect component to several queries in a declarative manner

Association

Associations are used by components to access related store documents that are linked in a document. They are also responsible for building the QueryDefinition that is used by the client to automatically fetch relationship data.

Hydrated documents used by components come with Association instances.

Kind: global class

new Association(target, name, doctype, options)

Example: The schema defines an author relationship :

const BOOK_SCHEMA = {
  relationships: {
     author: 'has-one'
  }
}

Hydrated books will have the author association instance under the author key. Accessing hydratedBook.author.data gives you the author from the store, for example :

{
  "name": "St-Exupery",
  "firstName": "Antoine",
  "_id": "antoine"
}

It is the responsibility of the relationship to decide how the relationship data is stored. For example, here since we use the default has-one relationship, the relationship data is stored in the relationships attribute of the original document (in our case here, our book would be

{
  "title": "Le petit prince",
  "relationships": {
    "author": {
      "data": {
        "doctype": "io.cozy.authors",
        "_id": "antoine"
      }
    }
  }
}

In the case of an “in-place” relationship, the relationship data is stored directly under the attribute named by the relationship (in our case author). Our book would be

{
    "title": "Le petit prince",
    "author": "antoine"
}

Each different type of Association may change:

Param Type Description
target object Original object containing raw data
name string Attribute under which the association is stored
doctype string Doctype of the documents managed by the association
options.dispatch function Store’s dispatch, comes from the client
options string

association.target : object

The original document declaring the relationship

Kind: instance property of Association

association.name : string

The name of the relationship.

Kind: instance property of Association
Example

'author'

association.doctype : string

Doctype of the relationship

Kind: instance property of Association
Example

'io.cozy.authors'

association.get : function

Returns the document from the store

Kind: instance property of Association

association.save : function

Saves the relationship in store.

Kind: instance property of Association

association.dispatch : function

Dispatch an action on the store.

Kind: instance property of Association

association.raw

Returns the raw relationship data as stored in the original document

For a document with relationships stored as JSON API spec:

const book = {
  title: 'Moby Dick',
  relationships: {
    author: {
      data: {
        doctype: 'io.cozy.authors',
        id: 'herman'
      }
    }
  }
 }

Raw value will be

{
  "doctype": "io.cozy.authors",
  "id": "herman"
}

Derived Associations need to implement this method.

Kind: instance property of Association

association.data

Returns the document(s) from the store

For document with relationships stored as JSON API spec :

const book = {
  title: 'Moby Dick',
  relationships: {
    author: {
      data: {
        doctype: 'io.cozy.authors',
        id: 'herman'
      }
    }
  }
 }

data will be

{
  "_id": "herman"
  "_type": "io.cozy.authors",
  "firstName": "herman",
  "name": "Melville"
}

Derived Associations need to implement this method.

Kind: instance property of Association

association.query(queryDefinition)

Performs a query to retrieve relationship documents.

Kind: instance method of Association

Param Type
queryDefinition QueryDefinition

association.mutate()

Performs a mutation on the relationship.

Kind: instance method of Association

Association.query() ⇒ QueryDefinition

Derived Associations need to implement this method.

Kind: static method of Association

HasMany

Related documents are stored in the relationships attribute of the object, following the JSON API spec.

Responsible for

Kind: global class

new HasMany()

const schema = {
  todos: {
     doctype: 'io.cozy.todos',
     relationships: {
       tasks: {
         doctype: 'io.cozy.tasks',
         type: 'has-many'
       }
     }
   }
}

const todo = {
  label: "Protect people's privacy",
  relationships: {
    tasks: {
      data: [
        {_id: 1, _type: 'io.cozy.tasks'},
        {_id: 2, _type: 'io.cozy.tasks'}
      ]
    }
  }
}

hasMany.addById()

Add a referenced document by id. You need to call save() in order to synchronize your document with the store.

Kind: instance method of HasMany
Todo

HasManyInPlace

Used when related documents are stored directly under the attribute with only the ids.

Kind: global class

new HasManyInPlace()

An example document representing a TODO. See as the related tasks are represented via ids.

const todo = {
  label: "Protect people's privacy",
  tasks: [1, 2]
}

Here is the Schema that would represent this kind of document. Components receiving todos via Querys would have an instance of HasManyInPlace as their tasks attribute.

const schema = {
  todos: {
     doctype: 'io.cozy.todos',
     relationships: {
       tasks: {
         doctype: 'io.cozy.tasks',
         type: 'has-many-in-place'
       }
     }
   }
}

const todo = {
  label: "Get rich",
  tasks: [1, 2]
}

HasManyTriggers ⇐ HasMany

Association used for konnectors to retrieve all their related triggers.

Kind: global class
Extends: HasMany

hasManyTriggers.addById()

Add a referenced document by id. You need to call save() in order to synchronize your document with the store.

Kind: instance method of HasManyTriggers
Todo

HasManyTriggers.query()

In this association the query is special, we need to fetch all the triggers having for the ‘konnector’ worker, and then filter them based on their message.konnector attribute

Kind: static method of HasManyTriggers

CozyClient

Responsible for

Kind: global class

new CozyClient(options)

Param Type Description
options Object
options.link Link Backward compatibility
options.links Array.Link List of links
options.schema Object Schema description for each doctypes
options.appMetadata Object Metadata about the application that will be used in ensureCozyMetadata

cozyClient.collection(doctype) ⇒ DocumentCollection

Forwards to a stack client instance and returns a DocumentCollection instance.

Kind: instance method of CozyClient

Param Type Description
doctype String The collection doctype.

cozyClient.getDocumentSavePlan(document, relationships) ⇒ Array.<Mutation>

Creates a list of mutations to execute to create a document and its relationships.

const baseDoc = { _type: 'io.cozy.todo', label: 'Go hiking' }
// relations can be arrays or single objects
const relationships = {
  attachments: [{ _id: 12345, _type: 'io.cozy.files' }, { _id: 6789, _type: 'io.cozy.files' }],
  bills: { _id: 9999, _type: 'io.cozy.bills' }
}
client.getDocumentSavePlan(baseDoc, relationships)

Kind: instance method of CozyClient
Returns: Array.<Mutation> - One or more mutation to execute

Param Type Description
document object The base document to create
relationships object The list of relationships to add, as a dictionnary. Keys should be relationship names and values the documents to link.

cozyClient.fetchRelationships()

Fetch relationships for a response (can be several docs). Fills the relationships attribute of each documents.

Can potentially result in several fetch requests. Queries are optimized before being sent.

Kind: instance method of CozyClient

cozyClient.hydrateDocument()

Instantiate relationships on a document

The original document is kept in the target attribute of the relationship

Kind: instance method of CozyClient

cozyClient.makeNewDocument()

Creates (locally) a new document for the given doctype. This document is hydrated : its relationships are there and working.

Kind: instance method of CozyClient

cozyClient.getAssociation()

Creates an association that is linked to the store.

Kind: instance method of CozyClient

cozyClient.getRelationshipStoreAccessors()

Returns the accessors that are given to the relationships for them to deal with the stores.

Relationships need to have access to the store to ping it when a modification (addById/removeById etc…) has been done. This wakes the store up, which in turn will update the <Query>s and re-render the data.

Kind: instance method of CozyClient

cozyClient.register(cozyURL) ⇒ object

Performs a complete OAuth flow using a Cordova webview for auth. The register method’s name has been chosen for compat reasons with the Authentication compo.

Kind: instance method of CozyClient
Returns: object - Contains the fetched token and the client information.

Param Type Description
cozyURL string Receives the URL of the cozy instance.

cozyClient.startOAuthFlow(openURLCallback) ⇒ object

Performs a complete OAuth flow, including updating the internal token at the end.

Kind: instance method of CozyClient
Returns: object - Contains the fetched token and the client information. These should be stored and used to restore the client.

Param Type Description
openURLCallback function Receives the URL to present to the user as a parameter, and should return a promise that resolves with the URL the user was redirected to after accepting the permissions.

cozyClient.renewAuthorization() ⇒ object

Renews the token if, for instance, new permissions are required or token has expired.

Kind: instance method of CozyClient
Returns: object - Contains the fetched token and the client information.

cozyClient.setData(data)

Directly set the data in the store, without using a query This is useful for cases like Pouch replication, which wants to set some data in the store.

Kind: instance method of CozyClient

Param Type Description
data Object

QueryDefinition

Chainable API to create query definitions to retrieve documents from a Cozy. QueryDefinitions are sent to links.

Kind: global class

new QueryDefinition(doctype, id, ids, selector, fields, indexedFields, sort, includes, referenced, limit, skip)

Param Type Description
doctype string The doctype of the doc.
id string The id of the doc.
ids Array The ids of the docs.
selector Object The selector to query the docs.
fields Array The fields to return.
indexedFields Array The fields to index.
sort Array The sorting params.
includes string The docs to include.
referenced string The referenced document.
limit number The document’s limit to return.
skip number The number of docs to skip.

queryDefinition.where(selector) ⇒ QueryDefinition

Query documents with a mango selector. Each field passed in the selector will be indexed, except if the indexField option is used.

Kind: instance method of QueryDefinition
Returns: QueryDefinition - The QueryDefinition object.

Param Type Description
selector Object The Mango selector.

queryDefinition.select(fields) ⇒ QueryDefinition

Specify which fields of each object should be returned. If it is omitted, the entire object is returned.

Kind: instance method of QueryDefinition
Returns: QueryDefinition - The QueryDefinition object.

Param Type Description
fields Array The fields to return.

queryDefinition.indexFields(fields) ⇒ QueryDefinition

Specify which fields should be indexed. This prevent the automatic indexing of the mango fields.

Kind: instance method of QueryDefinition
Returns: QueryDefinition - The QueryDefinition object.

Param Type Description
fields Array The fields to index.

queryDefinition.sortBy(sort) ⇒ QueryDefinition

Specify how to sort documents, following the sort syntax

Kind: instance method of QueryDefinition
Returns: QueryDefinition - The QueryDefinition object.

Param Type Description
sort Array The list of field name and direction pairs.

queryDefinition.include(includes) ⇒ QueryDefinition

Includes documents having a relationships with the ones queried. For example, query albums including the photos.

Kind: instance method of QueryDefinition
Returns: QueryDefinition - The QueryDefinition object.

Param Type Description
includes Array The documents to include.

queryDefinition.limitBy(limit) ⇒ QueryDefinition

Maximum number of documents returned, useful for pagination. Default is 100.

Kind: instance method of QueryDefinition
Returns: QueryDefinition - The QueryDefinition object.

Param Type Description
limit number The document’s limit.

queryDefinition.offset(skip) ⇒ QueryDefinition

Skip the first ‘n’ documents, where ‘n’ is the value specified.

Kind: instance method of QueryDefinition
Returns: QueryDefinition - The QueryDefinition object.

Param Type Description
skip number The number of documents to skip.

queryDefinition.referencedBy(document) ⇒ QueryDefinition

Use the file reference system

Kind: instance method of QueryDefinition
Returns: QueryDefinition - The QueryDefinition object.

Param Type Description
document Object The reference document

Schema

Stores information on a particular doctype.

const schema = new Schema({
  todos: {
    attributes: {
      label: {
        unique: true
      }
    },
    relationships: {
      author: 'has-one-in-place'
    }
  }
}, cozyStackClient)

Kind: global class

schema.getDoctypeSchema()

Returns the schema for a doctype

Kind: instance method of Schema

schema.getRelationship()

Returns the relationship for a given doctype/name

Kind: instance method of Schema

schema.validate()

Validates a document considering the descriptions in schema.attributes.

Kind: instance method of Schema

withClient(Component) ⇒ function

HOC to provide client from context as prop

Kind: global function
Returns: function - - Component that will receive client as prop

Param Type Description
Component Component wrapped component

queryConnect(querySpecs) ⇒ function

HOC creator to connect component to several queries in a declarative manner

Kind: global function
Returns: function - - HOC to apply to a component

Param Type Description
querySpecs object Definition of the queries