Skip to content

cozy-client / Association

Class: 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.

interface

description 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:

  • get raw: how the relationship data is stored (either as per the JSON API spec or in a custom way)
  • get data: how the store documents are then fetched from the store to be added to the hydrated document (.data method). View components will access hydratedDoc[relationshipName].data.
  • get query: how to build the query to fetch related documents

Hierarchy

Constructors

constructor

new Association(target, name, doctype, options)

Parameters

Name Type Description
target any 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 Object Options passed from the client
options.dispatch Function Store’s dispatch, comes from the client
options.get Function Get a document from the store
options.mutate Function Execute client mutate
options.query Function Execute client query
options.save Function Execute client save

Defined in

packages/cozy-client/src/associations/Association.js:76

Properties

dispatch

dispatch: Function

Dispatch an action on the store.

Defined in

packages/cozy-client/src/associations/Association.js:139


doctype

doctype: string

Doctype of the relationship

example ‘io.cozy.authors’

Defined in

packages/cozy-client/src/associations/Association.js:102


get

get: Function

Returns the document from the store

Defined in

packages/cozy-client/src/associations/Association.js:110


mutate

mutate: Function

Performs a mutation on the relationship.

function

Defined in

packages/cozy-client/src/associations/Association.js:125


name

name: string

The name of the relationship.

example ‘author’

Defined in

packages/cozy-client/src/associations/Association.js:95


query

query: Function

Performs a query to retrieve relationship documents.

param

function

Defined in

packages/cozy-client/src/associations/Association.js:117


save

save: Function

Saves the relationship in store.

Defined in

packages/cozy-client/src/associations/Association.js:132


target

target: any

The original document declaring the relationship

Defined in

packages/cozy-client/src/associations/Association.js:89

Accessors

data

get data(): any

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.

Returns

any

Defined in

packages/cozy-client/src/associations/Association.js:219


raw

get raw(): any

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.

Returns

any

Defined in

packages/cozy-client/src/associations/Association.js:181

Methods

query

Static query(document, client, assoc): QueryDefinition | CozyClientDocument

Derived Associations need to implement this method.

Parameters

Name Type Description
document CozyClientDocument Document to query
client any The CozyClient instance
assoc Association Association containing info on how to build the query to fetch related documents

Returns

QueryDefinition | CozyClientDocument

Defined in

packages/cozy-client/src/associations/Association.js:232