import Collection from 'kinto/lib/collection.js'

public class | source

Collection

Abstracts a collection of records stored in the local database, providing CRUD operations and synchronization helpers.

Test:

Collection

Static Member Summary

Static Public Members
public static get	strategy: Object Synchronization strategies.

Constructor Summary

Public Constructor
public	constructor(bucket: String, name: String, api: Api, options: Object) Constructor.

Member Summary

Public Members
public	api: KintoClient The Api instance.
public get	bucket: String The bucket name.
public	db: BaseAdapter The db adapter instance
public	events: EventEmitter The event emitter instance.
public	hooks: Object The list of hooks.
public	idSchema: Object The IdSchema instance.
public get	lastModified: Number The last modified timestamp.
public	localFields: Array The list of fields names that will remain local.
public get	name: String The collection name.
public	remoteTransformers: Array The list of remote transformers.

Private Members
private	_bucket: *
private	_lastModified: *
private	_name: *

Method Summary

Public Methods
public	applyHook(hookName: , payload: ): *
public	cleanLocalFields(record: Object): Object Return a copy of the specified record without the local fields.
public	async clear(): Promise Deletes every records in the current collection and marks the collection as never synced.
public	create(record: Object, options: Object): Promise Adds a record to the local database, asserting that none already exist with this ID.
public	delete(id: String, options: Object): Promise Same as Collection#delete, but wrapped in its own transaction.
public	async deleteAll(): Promise Same as Collection#deleteAll, but wrapped in its own transaction, execulding the parameter.
public	deleteAny(id: String): Promise The same as CollectionTransaction#deleteAny, but wrapped in its own transaction.
public	execute(doOperations: , objectPattern1: {"preloadIds": }): Promise Execute a bunch of operations in a transaction.
public	async gatherLocalChanges(): Promise Returns an object containing two lists:
public	get(id: String, options: Object): Promise Like CollectionTransaction#get, but wrapped in its own transaction.
public	getAny(id: String): Promise Like CollectionTransaction#getAny, but wrapped in its own transaction.
public	async importBulk(records: Array): Promise Load a list of records already synced with the remote server.
public	async importChanges(syncResultObject: SyncResultObject, decodedChanges: Array, strategy: String): Promise Imports remote changes into the local database.
public	async list(params: Object, options: Object): Promise Lists records from the local database.
public	async loadDump(records: Array): Promise this method was deprecated. Use {@link importBulk} instead. Load a list of records already synced with the remote server.
public	async metadata(): *
public	async pullChanges(client: KintoClient.Collection, syncResultObject: SyncResultObject, options: Object): Promise Fetch remote changes, import them to the local database, and handle conflicts according to `options.strategy`.
public	async pullMetadata(client: , options: {}):
public	async pushChanges(client: KintoClient.Collection, syncResultObject: SyncResultObject, changes: Object, options: Object): Promise Publish local changes to the remote server and updates the passed SyncResultObject with publication results.
public	async resetSyncStatus(): Promise Resets the local records as if they were never synced; existing records are marked as newly created, deleted records are dropped.
public	resolve(conflict: Object, resolution: Object): Promise Resolves a conflict, updating local record according to proposed resolution — keeping remote record `last_modified` value as a reference for further batch sending.
public	async sync(options: Object): Promise Synchronize remote and local data.
public	update(record: Object, options: Object): Promise Like CollectionTransaction#update, but wrapped in its own transaction.
public	upsert(record: Object): Promise Like CollectionTransaction#upsert, but wrapped in its own transaction.

Private Methods
private	async _applyPushedResults(syncResultObject: SyncResultObject, toApplyLocally: Array, conflicts: Array, strategy: String): Promise Imports the responses of pushed changes into the local database.
private	_decodeRecord(type: String, record: Object): Promise Decodes a record.
private	_encodeRecord(type: String, record: Object): Promise Encodes a record.
private	_handleConflicts(result: SyncResultObject, strategy: String): Promise<Array<Object>> Handles synchronization conflicts according to specified strategy.
private	_resolveRaw(conflict: , resolution: ): *
private	_validateHook(): Array Validate the passed hook is correct.
private	_validateHooks(hooks: Object \| undefined): Object Validates a list of hooks.
private	_validateIdSchema(idSchema: Object \| undefined): Object Validates an idSchema.
private	_validateRemoteTransformers(remoteTransformers: Array \| undefined): Array Validates a list of remote transformers.

Static Public Members

public static get strategy: Object source

Synchronization strategies. Available strategies are:

MANUAL: Conflicts will be reported in a dedicated array.
SERVER_WINS: Conflicts are resolved using remote data.
CLIENT_WINS: Conflicts are resolved using local data.

Public Constructors

public constructor(bucket: String, name: String, api: Api, options: Object) source

Constructor.

Options:

{BaseAdapter} adapter The DB adapter (default: IDB)

Params:

Name	Type	Attribute	Description
bucket	String		The bucket identifier.
name	String		The collection name.
api	Api		The Api instance.
options	Object		The options object.

Test:

Collection #constructor

Public Members

public api: KintoClient source

The Api instance.

public get bucket: String source

The bucket name.

public db: BaseAdapter source

The db adapter instance

public events: EventEmitter source

The event emitter instance.

public hooks: Object source

The list of hooks.

public idSchema: Object source

The IdSchema instance.

public get lastModified: Number source

The last modified timestamp.

public localFields: Array source

The list of fields names that will remain local.

public get name: String source

The collection name.

public remoteTransformers: Array source

The list of remote transformers.

Private Members

private _bucket: * source

private _lastModified: * source

private _name: * source

Public Methods

public applyHook(hookName: , payload: ): * source

Params:

Name	Type	Attribute	Description
hookName	*
payload	*

Return:

public cleanLocalFields(record: Object): Object source

Return a copy of the specified record without the local fields.

Params:

Name	Type	Attribute	Description
record	Object		A record with potential local fields.

Return:

Object

Test:

Collection #cleanLocalFields

public async clear(): Promise source

Deletes every records in the current collection and marks the collection as never synced.

Return:

Promise

Test:

Collection #clear

public create(record: Object, options: Object): Promise source

Adds a record to the local database, asserting that none already exist with this ID.

Note: If either the useRecordId or synced options are true, then the record object must contain the id field to be validated. If none of these options are true, an id is generated using the current IdSchema; in this case, the record passed must not have an id.

Options:

{Boolean} synced Sets record status to "synced" (default: false).

{Boolean} useRecordId Forces the id field from the record to be used,

                   instead of one that is generated automatically
                   (default: `false`).

Params:

Name	Type	Attribute	Description
record	Object
options	Object

Return:

Promise

Test:

Collection #create

public delete(id: String, options: Object): Promise source

Same as Collection#delete, but wrapped in its own transaction.

Options:

{Boolean} virtual: When set to true, doesn't actually delete the record, update its _status attribute to deleted instead (default: true)

Params:

Name	Type	Attribute	Description
id	String		The record's Id.
options	Object		The options object.

Return:

Promise

Test:

Collection #delete

public async deleteAll(): Promise source

Same as Collection#deleteAll, but wrapped in its own transaction, execulding the parameter.

Return:

Promise

Test:

Collection #deleteAll

public deleteAny(id: String): Promise source

The same as CollectionTransaction#deleteAny, but wrapped in its own transaction.

Params:

Name	Type	Attribute	Description
id	String		The record's Id.

Return:

Promise

Test:

Collection #deleteAny

public execute(doOperations: , objectPattern1: {"preloadIds": }): Promise source

Execute a bunch of operations in a transaction.

This transaction should be atomic -- either all of its operations will succeed, or none will.

The argument to this function is itself a function which will be called with a CollectionTransaction. Collection methods are available on this transaction, but instead of returning promises, they are synchronous. execute() returns a Promise whose value will be the return value of the provided function.

Most operations will require access to the record itself, which must be preloaded by passing its ID in the preloadIds option.

Options:

{Array} preloadIds: list of IDs to fetch at the beginning of the transaction

Params:

Name	Type	Attribute	Description
doOperations	*
objectPattern1	{"preloadIds": *}	optional default: {}

Return:

Promise

Resolves with the result of the given function when the transaction commits.

Test:

Collection #execute

public async gatherLocalChanges(): Promise source

Returns an object containing two lists:

toDelete: unsynced deleted records we can safely delete;
toSync: local updates to send to the server.

Return:

Promise

Test:

Collection #gatherLocalChanges

public get(id: String, options: Object): Promise source

Like CollectionTransaction#get, but wrapped in its own transaction.

Options:

{Boolean} includeDeleted: Include virtually deleted records.

Params:

Name	Type	Attribute	Description
id	String
options	Object

Return:

Promise

Test:

Collection #get

public getAny(id: String): Promise source

Like CollectionTransaction#getAny, but wrapped in its own transaction.

Params:

Name	Type	Attribute	Description
id	String

Return:

Promise

Test:

Collection #getAny

public async importBulk(records: Array): Promise source

Load a list of records already synced with the remote server.

The local records which are unsynced or whose timestamp is either missing or superior to those being loaded will be ignored.

Params:

Name	Type	Attribute	Description
records	Array		The previously exported list of records to load.

Return:

Promise

with the effectively imported records.

Test:

Collection #importBulk

public async importChanges(syncResultObject: SyncResultObject, decodedChanges: Array, strategy: String): Promise source

Imports remote changes into the local database. This method is in charge of detecting the conflicts, and resolve them according to the specified strategy.

Params:

Name	Type	Attribute	Description
syncResultObject	SyncResultObject		The sync result object.
decodedChanges	Array		The list of changes to import in the local database.
strategy	String		The Collection.strategy (default: MANUAL)

Return:

Promise

Test:

Collection #importChanges

public async list(params: Object, options: Object): Promise source

Lists records from the local database.

Params:

{Object} filters Filter the results (default: {}).
{String} order The order to apply (default: -last_modified).

Options:

{Boolean} includeDeleted: Include virtually deleted records.

Params:

Name	Type	Attribute	Description
params	Object		The filters and order to apply to the results.
options	Object		The options object.

Return:

Promise

Test:

Collection #list

public async loadDump(records: Array): Promise source

this method was deprecated. Use {@link importBulk} instead.

Load a list of records already synced with the remote server.

The local records which are unsynced or whose timestamp is either missing or superior to those being loaded will be ignored.

Params:

Name	Type	Attribute	Description
records	Array		The previously exported list of records to load.

Return:

Promise

with the effectively imported records.

Test:

Collection Deprecated #loadDump

public async metadata(): * source

Return:

public async pullChanges(client: KintoClient.Collection, syncResultObject: SyncResultObject, options: Object): Promise source

Fetch remote changes, import them to the local database, and handle conflicts according to options.strategy. Then, updates the passed SyncResultObject with import results.

Options:

{String} strategy: The selected sync strategy.
{String} expectedTimestamp: A timestamp to use as a "cache busting" query parameter.
{Array<String>} exclude: A list of record ids to exclude from pull.
{Object} headers: The HTTP headers to use in the request.
{int} retry: The number of retries to do if the HTTP request fails.
{int} lastModified: The timestamp to use in ?_since query.

Params:

Name	Type	Attribute	Description
client	KintoClient.Collection		Kinto client Collection instance.
syncResultObject	SyncResultObject		The sync result object.
options	Object		The options object.

Return:

Promise

Test:

Collection #pullChanges

public async pullMetadata(client: , options: {}): source

Params:

Name	Type	Attribute	Description
client	*
options	{}	optional default: {}

Return:

Test:

Collection #pullMetadata

public async pushChanges(client: KintoClient.Collection, syncResultObject: SyncResultObject, changes: Object, options: Object): Promise source

Publish local changes to the remote server and updates the passed SyncResultObject with publication results.

Options:

{String} strategy: The selected sync strategy.
{Object} headers: The HTTP headers to use in the request.
{int} retry: The number of retries to do if the HTTP request fails.

Params:

Name	Type	Attribute	Description
client	KintoClient.Collection		Kinto client Collection instance.
syncResultObject	SyncResultObject		The sync result object.
changes	Object		The change object.
changes.toDelete	Array		The list of records to delete.
changes.toSync	Array		The list of records to create/update.
options	Object		The options object.

Return:

Promise

Test:

Collection #pushChanges

public async resetSyncStatus(): Promise source

Resets the local records as if they were never synced; existing records are marked as newly created, deleted records are dropped.

A next call to Collection.sync will thus republish the whole content of the local collection to the server.

Return:

Promise

Resolves with the number of processed records.

Test:

Collection #resetSyncStatus

public resolve(conflict: Object, resolution: Object): Promise source

Resolves a conflict, updating local record according to proposed resolution — keeping remote record last_modified value as a reference for further batch sending.

Params:

Name	Type	Attribute	Description
conflict	Object		The conflict object.
resolution	Object		The proposed record.

Return:

Promise

Test:

Collection #resolve

public async sync(options: Object): Promise source

Synchronize remote and local data. The promise will resolve with a SyncResultObject, though will reject:

if the server is currently backed off;
if the server has been detected flushed.

Options:

{Object} headers: HTTP headers to attach to outgoing requests.
{String} expectedTimestamp: A timestamp to use as a "cache busting" query parameter.
{Number} retry: Number of retries when server fails to process the request (default: 1).
{Collection.strategy} strategy: See Collection.strategy.
{Boolean} ignoreBackoff: Force synchronization even if server is currently backed off.
{String} bucket: The remove bucket id to use (default: null)
{String} collection: The remove collection id to use (default: null)
{String} remote The remote Kinto server endpoint to use (default: null).

Params:

Name	Type	Attribute	Description
options	Object		Options.

Return:

Promise

Throw:

Error

If an invalid remote option is passed.

Test:

Collection #sync

public update(record: Object, options: Object): Promise source

Like CollectionTransaction#update, but wrapped in its own transaction.

Options:

{Boolean} synced: Sets record status to "synced" (default: false)
{Boolean} patch: Extends the existing record instead of overwriting it (default: false)

Params:

Name	Type	Attribute	Description
record	Object
options	Object

Return:

Promise

Test:

Collection #update

public upsert(record: Object): Promise source

Like CollectionTransaction#upsert, but wrapped in its own transaction.

Params:

Name	Type	Attribute	Description
record	Object

Return:

Promise

Private Methods

private async _applyPushedResults(syncResultObject: SyncResultObject, toApplyLocally: Array, conflicts: Array, strategy: String): Promise source

Imports the responses of pushed changes into the local database. Basically it stores the timestamp assigned by the server into the local database.

Params:

Name	Type	Attribute	Description
syncResultObject	SyncResultObject		The sync result object.
toApplyLocally	Array		The list of changes to import in the local database.
conflicts	Array		The list of conflicts that have to be resolved.
strategy	String		The Collection.strategy.

Return:

Promise

private _decodeRecord(type: String, record: Object): Promise source

Decodes a record.

Params:

Name	Type	Attribute	Description
type	String		Either "remote" or "local".
record	Object		The record object to decode.

Return:

Promise

private _encodeRecord(type: String, record: Object): Promise source

Encodes a record.

Params:

Name	Type	Attribute	Description
type	String		Either "remote" or "local".
record	Object		The record object to encode.

Return:

Promise

private _handleConflicts(result: SyncResultObject, strategy: String): Promise<Array<Object>> source

Handles synchronization conflicts according to specified strategy.

Params:

Name	Type	Attribute	Description
result	SyncResultObject		The sync result object.
strategy	String		The Collection.strategy.

Return:

Promise<Array<Object>>

The resolved conflicts, as an array of {accepted, rejected} objects

private _resolveRaw(conflict: , resolution: ): * source

Params:

Name	Type	Attribute	Description
conflict	*
resolution	*

Return:

private _validateHook(): Array source

Validate the passed hook is correct.

Params:

Name	Type	Attribute	Description
hook.	Array \| undefined

Return:

Array

private _validateHooks(hooks: Object | undefined): Object source

Validates a list of hooks.

Params:

Name	Type	Attribute	Description
hooks	Object \| undefined

Return:

Object

private _validateIdSchema(idSchema: Object | undefined): Object source

Validates an idSchema.

Params:

Name	Type	Attribute	Description
idSchema	Object \| undefined

Return:

Object

private _validateRemoteTransformers(remoteTransformers: Array | undefined): Array source

Validates a list of remote transformers.

Params:

Name	Type	Attribute	Description
remoteTransformers	Array \| undefined

Return:

Array

Collection

Test:

Static Member Summary

Constructor Summary

Member Summary

Method Summary

Static Public Members

public static get strategy: Object source

Public Constructors

public constructor(bucket: String, name: String, api: Api, options: Object) source

Params:

Test:

Public Members

public api: KintoClient source

public get bucket: String source

public db: BaseAdapter source

public events: EventEmitter source

public hooks: Object source

public idSchema: Object source

public get lastModified: Number source

public localFields: Array source

public get name: String source

public remoteTransformers: Array source

Private Members

private _bucket: * source

private _lastModified: * source

private _name: * source

Public Methods

public applyHook(hookName: *, payload: *): * source

Params:

Return:

public cleanLocalFields(record: Object): Object source

Params:

Return:

Test:

public async clear(): Promise source

Return:

Test:

public create(record: Object, options: Object): Promise source

Params:

Return:

Test:

public delete(id: String, options: Object): Promise source

Params:

Return:

Test:

public async deleteAll(): Promise source

Return:

Test:

public deleteAny(id: String): Promise source

Params:

Return:

Test:

public execute(doOperations: *, objectPattern1: {"preloadIds": *}): Promise source

Params:

Return:

Test:

public async gatherLocalChanges(): Promise source

Return:

Test:

public get(id: String, options: Object): Promise source

Params:

Return:

Test:

public getAny(id: String): Promise source

Params:

Return:

Test:

public async importBulk(records: Array): Promise source

Params:

Return:

Test:

public async importChanges(syncResultObject: SyncResultObject, decodedChanges: Array, strategy: String): Promise source

Params:

Return:

Test:

public async list(params: Object, options: Object): Promise source

Params:

Return:

Test:

public applyHook(hookName: , payload: ): * source

public execute(doOperations: , objectPattern1: {"preloadIds": }): Promise source

public async pullMetadata(client: , options: {}): source

private _resolveRaw(conflict: , resolution: ): * source