cozy-pouch-link.md

Classes

PouchLink

Link to be passed to a CozyClient instance to support CouchDB. It instantiates PouchDB collections for each doctype that it supports and knows how to respond to queries and mutations.

Loop

Utility to call a function (task) periodically and on demand immediately.

Public API

• start
• stop
• scheduleImmediateTask
• waitForCurrentTask

PouchManager

Handles the lifecycle of several pouches

• Creates/Destroys the pouches
• Replicates periodically

Constants

persistLastReplicatedDocID

Persist the last replicated doc id for a doctype

getLastReplicatedDocID ⇒ string

Get the last replicated doc id for a doctype

destroyAllLastReplicatedDocID

Destroy all the replicated doc id

getPersistedSyncedDoctypes ⇒ object

Get the persisted doctypes

destroySyncedDoctypes

Destroy the synced doctypes

persistDoctypeLastSequence

Persist the last CouchDB sequence for a synced doctype

getDoctypeLastSequence ⇒ string

Get the last CouchDB sequence for a doctype

destroyAllDoctypeLastSequence

Destroy all the last sequence

destroyDoctypeLastSequence

Destroy the last sequence for a doctype

persistWarmedUpQueries

Persist the warmed up queries

getPersistedWarmedUpQueries ⇒ object

Get the warmed up queries

destroyWarmedUpQueries

Destroy the warmed queries

getAdapterName ⇒ string

Get the adapter name

persistAdapterName

Persist the adapter name

fetchRemoteInstance ⇒ object

Fetch remote instance

fetchRemoteLastSequence ⇒ string

Fetch last sequence from remote instance

replicateAllDocs ⇒ Array

Replicate all docs locally from a remote URL.

It uses the _all_docs view, and bulk insert the docs. Note it saves the last replicated _id for each run and starts from there in case the process stops before the end.

getDatabaseName ⇒ string

Get the database name based on prefix and doctype

getPrefix ⇒ string

Get the URI prefix

Functions

getQueryAlias(query) ⇒ string

Typedefs

SyncStatus : "idle" | "replicating"

MigrationParams : object

Migrate the current adapter

SyncInfo : object

Persist the synchronized doctypes

MigrationParams ⇒ object

Migrate a PouchDB database to a new adapter.

PouchLink

Link to be passed to a CozyClient instance to support CouchDB. It instantiates PouchDB collections for each doctype that it supports and knows how to respond to queries and mutations.

Kind: global class

• PouchLink
  • new PouchLink([opts])
  • .replicationStatus : Record.<string, SyncStatus>
  • .getPouchAdapterName ⇒ string
  • .handleOnSync()
  • .startReplication() ⇒ void
  • .stopReplication() ⇒ void
  • .needsToWaitWarmup(doctype) ⇒ boolean

new PouchLink([opts])

constructor - Initializes a new PouchLink

Returns: object - The PouchLink instance

Param	Type	Default	Description
[opts]	object	{}
[opts.replicationInterval]	number		Milliseconds between replications
opts.doctypes	Array.<string>		Doctypes to replicate
opts.doctypesReplicationOptions	Array.<object>		A mapping from doctypes to replication options. All pouch replication options can be used, as well as the "strategy" option that determines which way the replication is done (can be "sync", "fromRemote" or "toRemote")

pouchLink.replicationStatus : Record.<string, SyncStatus>

• Stores replication states per doctype

Kind: instance property of PouchLink

pouchLink.getPouchAdapterName ⇒ string

Return the PouchDB adapter name. Should be IndexedDB for newest adapters.

Kind: instance property of PouchLink
Returns: string - The adapter name

pouchLink.handleOnSync()

Receives PouchDB updates (documents grouped by doctype). Normalizes the data (.id -> ._id, .rev -> _rev). Passes the data to the client and to the onSync handler.

Emits an event (pouchlink:sync:end) when the sync (all doctypes) is done

Kind: instance method of PouchLink

pouchLink.startReplication() ⇒ void

User of the link can call this to start ongoing replications. Typically, it can be used when the application regains focus.

Emits pouchlink:sync:start event when the replication begins

Kind: instance method of PouchLink
Access: public

pouchLink.stopReplication() ⇒ void

User of the link can call this to stop ongoing replications. Typically, it can be used when the applications loses focus.

Emits pouchlink:sync:stop event

Kind: instance method of PouchLink
Access: public

pouchLink.needsToWaitWarmup(doctype) ⇒ boolean

Check if there is warmup queries for this doctype and return if those queries are already warmed up or not

Kind: instance method of PouchLink
Returns: boolean - the need to wait for the warmup

Param	Type	Description
doctype	string	Doctype to check

Loop

Utility to call a function (task) periodically and on demand immediately.

Public API

• start
• stop
• scheduleImmediateTask
• waitForCurrentTask

Kind: global class

• Loop
  • .start()
  • .stop()
  • .runImmediateTasks()
  • .scheduleImmediateTask(task)
  • .runTask()
  • .round()

loop.start()

Starts the loop. Will run the task periodically each this.delay ms. Ignores multiple starts.

Kind: instance method of Loop

loop.stop()

Stops the loop, clears immediate tasks. Cancels current task if possible

Kind: instance method of Loop

loop.runImmediateTasks()

Flushes the immediate tasks list and calls each task. Each task is awaited before the next is started.

Kind: instance method of Loop

loop.scheduleImmediateTask(task)

Schedules a task to be run immediately at next round. Ignored if loop is not started. If not task is passed, the default task from the loop is used.

Kind: instance method of Loop

Param	Type	Default	Description
task	function		Optional custom function to be run immediately

loop.runTask()

Calls and saves current task. Stops loop in case of error of the task.

Kind: instance method of Loop

loop.round()

Runs immediate tasks and then schedule the next round. Immediate tasks are called sequentially without delay There is a delay between immediate tasks and normal periodic tasks.

Kind: instance method of Loop

PouchManager

Handles the lifecycle of several pouches

• Creates/Destroys the pouches
• Replicates periodically

Kind: global class

• PouchManager
  • .ensureDatabasesExist()
  • .startReplicationLoop()
  • .stopReplicationLoop()
  • .syncImmediately()
  • .replicateOnce()

pouchManager.ensureDatabasesExist()

Via a call to info() we ensure the database exist on the remote side. This is done only once since after the first call, we are sure that the databases have been created.

Kind: instance method of PouchManager

pouchManager.startReplicationLoop()

Starts periodic syncing of the pouches

Kind: instance method of PouchManager

pouchManager.stopReplicationLoop()

Stop periodic syncing of the pouches

Kind: instance method of PouchManager

pouchManager.syncImmediately()

If a replication is currently ongoing, will start a replication just after it has finished. Otherwise it will start a replication immediately

Kind: instance method of PouchManager

pouchManager.replicateOnce()

Starts replication

Kind: instance method of PouchManager

persistLastReplicatedDocID

Persist the last replicated doc id for a doctype

Kind: global constant

Param	Type	Description
doctype	string	The replicated doctype
id	string	The docid

getLastReplicatedDocID ⇒ string

Get the last replicated doc id for a doctype

Kind: global constant
Returns: string - The last replicated docid

Param	Type	Description
doctype	string	The doctype

destroyAllLastReplicatedDocID

Destroy all the replicated doc id

Kind: global constant

getPersistedSyncedDoctypes ⇒ object

Get the persisted doctypes

Kind: global constant
Returns: object - The synced doctypes

destroySyncedDoctypes

Destroy the synced doctypes

Kind: global constant

persistDoctypeLastSequence

Persist the last CouchDB sequence for a synced doctype

Kind: global constant

Param	Type	Description
doctype	string	The synced doctype
sequence	string	The sequence hash

getDoctypeLastSequence ⇒ string

Get the last CouchDB sequence for a doctype

Kind: global constant
Returns: string - the last sequence

Param	Type	Description
doctype	string	The doctype

destroyAllDoctypeLastSequence

Destroy all the last sequence

Kind: global constant

destroyDoctypeLastSequence

Destroy the last sequence for a doctype

Kind: global constant

Param	Type	Description
doctype	string	The doctype

persistWarmedUpQueries

Persist the warmed up queries

Kind: global constant

Param	Type	Description
warmedUpQueries	object	The warmedup queries

getPersistedWarmedUpQueries ⇒ object

Get the warmed up queries

Kind: global constant
Returns: object - the warmed up queries

destroyWarmedUpQueries

Destroy the warmed queries

Kind: global constant

getAdapterName ⇒ string

Get the adapter name

Kind: global constant
Returns: string - The adapter name

persistAdapterName

Persist the adapter name

Kind: global constant

Param	Type	Description
adapter	string	The adapter name

fetchRemoteInstance ⇒ object

Fetch remote instance

Kind: global constant
Returns: object - The instance response

Param	Type	Description
url	URL	The remote instance URL, including the credentials
params	object	The params to query the remote instance

fetchRemoteLastSequence ⇒ string

Fetch last sequence from remote instance

Kind: global constant
Returns: string - The last sequence

Param	Type	Description
baseUrl	string	The base URL of the remote instance

replicateAllDocs ⇒ Array

Replicate all docs locally from a remote URL.

It uses the _all_docs view, and bulk insert the docs. Note it saves the last replicated _id for each run and starts from there in case the process stops before the end.

Kind: global constant
Returns: Array - The retrieved documents

Param	Type	Description
db	object	Pouch instance
baseUrl	string	The remote instance
doctype	string	The doctype to replicate

getDatabaseName ⇒ string

Get the database name based on prefix and doctype

Kind: global constant
Returns: string - The database name

Param	Type	Description
prefix	string	The URL prefix
doctype	string	The database doctype

getPrefix ⇒ string

Get the URI prefix

Kind: global constant
Returns: string - The URI prefix

Param	Type	Description
uri	string	The Cozy URI

getQueryAlias(query) ⇒ string

Kind: global function
Returns: string - alias

Param	Type	Description
query	QueryDefinition	The query definition whose name we're getting

SyncStatus : "idle" | "replicating"

Kind: global typedef

MigrationParams : object

Migrate the current adapter

Kind: global typedef

Param	Type	Description
params	MigrationParams	Migration params

Properties

Name	Type	Description
[fromAdapter]	string	The current adapter type, e.g. 'idb'
[toAdapter]	string	The new adapter type, e.g. 'indexeddb'
[url]	string	The Cozy URL
[plugins]	Array.<object>	The PouchDB plugins

SyncInfo : object

Persist the synchronized doctypes

Kind: global typedef

Param	Type	Description
syncedDoctypes	Record.<string, SyncInfo>	The sync doctypes

Properties

Name	Type
Date	string

MigrationParams ⇒ object

Migrate a PouchDB database to a new adapter.

Kind: global typedef
Returns: object - - The migrated pouch

Param	Type	Description
params	MigrationParams	The migration params

Properties

Name	Type	Description
[dbName]	string	The database name
[fromAdapter]	string	The current adapter type, e.g. 'idb'
[toAdapter]	string	The new adapter type, e.g. 'indexeddb'