kinto
Version:
An Offline-First JavaScript client for Kinto.
451 lines (450 loc) • 18.5 kB
TypeScript
import KintoClientBase, { PaginatedParams, PaginationResult } from "./base";
import Bucket from "./bucket";
import { Permission, KintoResponse, KintoIdObject, KintoObject, Attachment, OperationResponse, MappableObject } from "../types";
import { AggregateResponse } from "./batch";
export interface CollectionOptions {
headers?: Record<string, string>;
safe?: boolean;
retry?: number;
}
/**
* Abstract representation of a selected collection.
*
*/
export default class Collection {
client: KintoClientBase;
private bucket;
name: string;
private _endpoints;
private _retry;
private _safe;
private _headers;
/**
* Constructor.
*
* @param {KintoClient} client The client instance.
* @param {Bucket} bucket The bucket instance.
* @param {String} name The collection name.
* @param {Object} [options={}] The options object.
* @param {Object} [options.headers] The headers object option.
* @param {Boolean} [options.safe] The safe option.
* @param {Number} [options.retry] The retry option.
* @param {Boolean} [options.batch] (Private) Whether this
* Collection is operating as part of a batch.
*/
constructor(client: KintoClientBase, bucket: Bucket, name: string, options?: CollectionOptions);
get execute(): KintoClientBase["execute"];
/**
* Get the value of "headers" for a given request, merging the
* per-request headers with our own "default" headers.
*
* @private
*/
private _getHeaders;
/**
* Get the value of "safe" for a given request, using the
* per-request option if present or falling back to our default
* otherwise.
*
* @private
* @param {Object} options The options for a request.
* @returns {Boolean}
*/
private _getSafe;
/**
* As _getSafe, but for "retry".
*
* @private
*/
private _getRetry;
/**
* Retrieves the total number of records in this collection.
*
* @param {Object} [options={}] The options object.
* @param {Object} [options.headers] The headers object option.
* @param {Number} [options.retry=0] Number of retries to make
* when faced with transient errors.
* @return {Promise<Number, Error>}
*/
getTotalRecords(options?: {
headers?: Record<string, string>;
retry?: number;
}): Promise<number>;
/**
* Retrieves the ETag of the records list, for use with the `since` filtering option.
*
* @param {Object} [options={}] The options object.
* @param {Object} [options.headers] The headers object option.
* @param {Number} [options.retry=0] Number of retries to make
* when faced with transient errors.
* @return {Promise<String, Error>}
*/
getRecordsTimestamp(options?: {
headers?: Record<string, string>;
retry?: number;
}): Promise<string | null>;
/**
* Retrieves collection data.
*
* @param {Object} [options={}] The options object.
* @param {Object} [options.headers] The headers object option.
* @param {Object} [options.query] Query parameters to pass in
* the request. This might be useful for features that aren't
* yet supported by this library.
* @param {Array} [options.fields] Limit response to
* just some fields.
* @param {Number} [options.retry=0] Number of retries to make
* when faced with transient errors.
* @return {Promise<Object, Error>}
*/
getData<T>(options?: {
headers?: Record<string, string>;
query?: {
[key: string]: string;
};
fields?: string[];
retry?: number;
}): Promise<T>;
/**
* Set collection data.
* @param {Object} data The collection data object.
* @param {Object} [options={}] The options object.
* @param {Object} [options.headers] The headers object option.
* @param {Number} [options.retry=0] Number of retries to make
* when faced with transient errors.
* @param {Boolean} [options.safe] The safe option.
* @param {Boolean} [options.patch] The patch option.
* @param {Number} [options.last_modified] The last_modified option.
* @return {Promise<Object, Error>}
*/
setData<T extends MappableObject>(data: T & {
last_modified?: number;
}, options?: {
headers?: Record<string, string>;
safe?: boolean;
retry?: number;
patch?: boolean;
last_modified?: number;
permissions?: {
[key in Permission]?: string[];
};
}): Promise<KintoResponse<T>>;
/**
* Retrieves the list of permissions for this collection.
*
* @param {Object} [options={}] The options object.
* @param {Object} [options.headers] The headers object option.
* @param {Number} [options.retry=0] Number of retries to make
* when faced with transient errors.
* @return {Promise<Object, Error>}
*/
getPermissions(options?: {
headers?: Record<string, string>;
retry?: number;
}): Promise<{
[key in Permission]?: string[];
}>;
/**
* Replaces all existing collection permissions with the ones provided.
*
* @param {Object} permissions The permissions object.
* @param {Object} [options={}] The options object
* @param {Object} [options.headers] The headers object option.
* @param {Number} [options.retry=0] Number of retries to make
* when faced with transient errors.
* @param {Boolean} [options.safe] The safe option.
* @param {Number} [options.last_modified] The last_modified option.
* @return {Promise<Object, Error>}
*/
setPermissions(permissions: {
[key in Permission]?: string[];
}, options?: {
safe?: boolean;
headers?: Record<string, string>;
retry?: number;
last_modified?: number;
}): Promise<KintoResponse<{}>>;
/**
* Append principals to the collection permissions.
*
* @param {Object} permissions The permissions object.
* @param {Object} [options={}] The options object
* @param {Boolean} [options.safe] The safe option.
* @param {Object} [options.headers] The headers object option.
* @param {Number} [options.retry=0] Number of retries to make
* when faced with transient errors.
* @param {Object} [options.last_modified] The last_modified option.
* @return {Promise<Object, Error>}
*/
addPermissions(permissions: {
[key in Permission]?: string[];
}, options?: {
safe?: boolean;
headers?: Record<string, string>;
retry?: number;
last_modified?: number;
}): Promise<KintoResponse<{}>>;
/**
* Remove principals from the collection permissions.
*
* @param {Object} permissions The permissions object.
* @param {Object} [options={}] The options object
* @param {Boolean} [options.safe] The safe option.
* @param {Object} [options.headers] The headers object option.
* @param {Number} [options.retry=0] Number of retries to make
* when faced with transient errors.
* @param {Object} [options.last_modified] The last_modified option.
* @return {Promise<Object, Error>}
*/
removePermissions(permissions: {
[key in Permission]?: string[];
}, options?: {
safe?: boolean;
headers?: Record<string, string>;
retry?: number;
last_modified?: number;
}): Promise<KintoResponse<{}>>;
/**
* Creates a record in current collection.
*
* @param {Object} record The record to create.
* @param {Object} [options={}] The options object.
* @param {Object} [options.headers] The headers object option.
* @param {Number} [options.retry=0] Number of retries to make
* when faced with transient errors.
* @param {Boolean} [options.safe] The safe option.
* @param {Object} [options.permissions] The permissions option.
* @return {Promise<Object, Error>}
*/
createRecord<T extends MappableObject>(record: T & {
id?: string;
}, options?: {
headers?: Record<string, string>;
retry?: number;
safe?: boolean;
permissions?: {
[key in Permission]?: string[];
};
}): Promise<KintoResponse<T>>;
/**
* Adds an attachment to a record, creating the record when it doesn't exist.
*
* @param {String} dataURL The data url.
* @param {Object} [record={}] The record data.
* @param {Object} [options={}] The options object.
* @param {Object} [options.headers] The headers object option.
* @param {Number} [options.retry=0] Number of retries to make
* when faced with transient errors.
* @param {Boolean} [options.safe] The safe option.
* @param {Number} [options.last_modified] The last_modified option.
* @param {Object} [options.permissions] The permissions option.
* @param {String} [options.filename] Force the attachment filename.
* @return {Promise<Object, Error>}
*/
addAttachment(dataURI: string, record?: {
[key: string]: string;
}, options?: {
headers?: Record<string, string>;
retry?: number;
safe?: boolean;
last_modified?: number;
permissions?: {
[key in Permission]?: string[];
};
filename?: string;
}): Promise<KintoResponse<{
attachment: Attachment;
}>>;
/**
* Removes an attachment from a given record.
*
* @param {Object} recordId The record id.
* @param {Object} [options={}] The options object.
* @param {Object} [options.headers] The headers object option.
* @param {Number} [options.retry=0] Number of retries to make
* when faced with transient errors.
* @param {Boolean} [options.safe] The safe option.
* @param {Number} [options.last_modified] The last_modified option.
*/
removeAttachment(recordId: string, options?: {
headers?: Record<string, string>;
retry?: number;
safe?: boolean;
last_modified?: number;
}): Promise<{}>;
/**
* Updates a record in current collection.
*
* @param {Object} record The record to update.
* @param {Object} [options={}] The options object.
* @param {Object} [options.headers] The headers object option.
* @param {Number} [options.retry=0] Number of retries to make
* when faced with transient errors.
* @param {Boolean} [options.safe] The safe option.
* @param {Number} [options.last_modified] The last_modified option.
* @param {Object} [options.permissions] The permissions option.
* @return {Promise<Object, Error>}
*/
updateRecord<T>(record: T & {
id: string;
}, options?: {
headers?: Record<string, string>;
retry?: number;
safe?: boolean;
last_modified?: number;
permissions?: {
[key in Permission]?: string[];
};
patch?: boolean;
}): Promise<KintoResponse<T>>;
/**
* Deletes a record from the current collection.
*
* @param {Object|String} record The record to delete.
* @param {Object} [options={}] The options object.
* @param {Object} [options.headers] The headers object option.
* @param {Number} [options.retry=0] Number of retries to make
* when faced with transient errors.
* @param {Boolean} [options.safe] The safe option.
* @param {Number} [options.last_modified] The last_modified option.
* @return {Promise<Object, Error>}
*/
deleteRecord(record: string | KintoIdObject, options?: {
headers?: Record<string, string>;
retry?: number;
safe?: boolean;
last_modified?: number;
}): Promise<KintoResponse<{
deleted: boolean;
}>>;
/**
* Deletes records from the current collection.
*
* Sorting is done by passing a `sort` string option:
*
* - The field to order the results by, prefixed with `-` for descending.
* Default: `-last_modified`.
*
* @see http://kinto.readthedocs.io/en/stable/api/1.x/sorting.html
*
* Filtering is done by passing a `filters` option object:
*
* - `{fieldname: "value"}`
* - `{min_fieldname: 4000}`
* - `{in_fieldname: "1,2,3"}`
* - `{not_fieldname: 0}`
* - `{exclude_fieldname: "0,1"}`
*
* @see http://kinto.readthedocs.io/en/stable/api/1.x/filtering.html
*
* @param {Object} [options={}] The options object.
* @param {Object} [options.headers] The headers object option.
* @param {Number} [options.retry=0] Number of retries to make
* when faced with transient errors.
* @param {Object} [options.filters={}] The filters object.
* @param {String} [options.sort="-last_modified"] The sort field.
* @param {String} [options.at] The timestamp to get a snapshot at.
* @param {String} [options.limit=null] The limit field.
* @param {String} [options.pages=1] The number of result pages to aggregate.
* @param {Number} [options.since=null] Only retrieve records modified since the provided timestamp.
* @param {Array} [options.fields] Limit response to just some fields.
* @return {Promise<Object, Error>}
*/
deleteRecords<T extends KintoObject>(options?: PaginatedParams & {
headers?: Record<string, string>;
retry?: number;
}): Promise<PaginationResult<T>>;
/**
* Retrieves a record from the current collection.
*
* @param {String} id The record id to retrieve.
* @param {Object} [options={}] The options object.
* @param {Object} [options.headers] The headers object option.
* @param {Object} [options.query] Query parameters to pass in
* the request. This might be useful for features that aren't
* yet supported by this library.
* @param {Array} [options.fields] Limit response to
* just some fields.
* @param {Number} [options.retry=0] Number of retries to make
* when faced with transient errors.
* @return {Promise<Object, Error>}
*/
getRecord<T>(id: string, options?: {
headers?: Record<string, string>;
query?: {
[key: string]: string;
};
fields?: string[];
retry?: number;
}): Promise<KintoResponse<T>>;
/**
* Lists records from the current collection.
*
* Sorting is done by passing a `sort` string option:
*
* - The field to order the results by, prefixed with `-` for descending.
* Default: `-last_modified`.
*
* @see http://kinto.readthedocs.io/en/stable/api/1.x/sorting.html
*
* Filtering is done by passing a `filters` option object:
*
* - `{fieldname: "value"}`
* - `{min_fieldname: 4000}`
* - `{in_fieldname: "1,2,3"}`
* - `{not_fieldname: 0}`
* - `{exclude_fieldname: "0,1"}`
*
* @see http://kinto.readthedocs.io/en/stable/api/1.x/filtering.html
*
* Paginating is done by passing a `limit` option, then calling the `next()`
* method from the resolved result object to fetch the next page, if any.
*
* @param {Object} [options={}] The options object.
* @param {Object} [options.headers] The headers object option.
* @param {Number} [options.retry=0] Number of retries to make
* when faced with transient errors.
* @param {Object} [options.filters={}] The filters object.
* @param {String} [options.sort="-last_modified"] The sort field.
* @param {String} [options.at] The timestamp to get a snapshot at.
* @param {String} [options.limit=null] The limit field.
* @param {String} [options.pages=1] The number of result pages to aggregate.
* @param {Number} [options.since=null] Only retrieve records modified since the provided timestamp.
* @param {Array} [options.fields] Limit response to just some fields.
* @return {Promise<Object, Error>}
*/
listRecords<T extends KintoObject>(options?: PaginatedParams & {
headers?: Record<string, string>;
retry?: number;
at?: number;
}): Promise<PaginationResult<T>>;
/**
* @private
*/
isHistoryComplete(): Promise<boolean>;
/**
* @private
*/
getSnapshot<T extends KintoObject>(at: number, options?: {
headers?: Record<string, string>;
retry?: number;
at?: number;
}): Promise<PaginationResult<T>>;
/**
* Performs batch operations at the current collection level.
*
* @param {Function} fn The batch operation function.
* @param {Object} [options={}] The options object.
* @param {Object} [options.headers] The headers object option.
* @param {Boolean} [options.safe] The safe option.
* @param {Number} [options.retry] The retry option.
* @param {Boolean} [options.aggregate] Produces a grouped result object.
* @return {Promise<Object, Error>}
*/
batch(fn: (client: Collection) => void, options?: {
headers?: Record<string, string>;
safe?: boolean;
retry?: number;
aggregate?: boolean;
}): Promise<OperationResponse<KintoObject>[] | AggregateResponse>;
}