kinto/lib/http/bucket.d.ts

An Offline-First JavaScript client for Kinto.

import Collection from "./collection";
import KintoClientBase, { PaginatedParams, PaginationResult } from "./base";
import { KintoIdObject, Permission, KintoResponse, HistoryEntry, KintoObject, Group, OperationResponse, MappableObject } from "../types";
import { AggregateResponse } from "./batch";
export interface BucketOptions {
    safe?: boolean;
    headers?: Record<string, string>;
    retry?: number;
}
/**
 * Abstract representation of a selected bucket.
 *
 */
export default class Bucket {
    private client;
    name: string;
    private _endpoints;
    private _retry;
    private _safe;
    private _headers;
    /**
     * Constructor.
     *
     * @param  {KintoClient} client            The client instance.
     * @param  {String}      name              The bucket name.
     * @param  {Object}      [options={}]      The headers object option.
     * @param  {Object}      [options.headers] The headers object option.
     * @param  {Boolean}     [options.safe]    The safe option.
     * @param  {Number}      [options.retry]   The retry option.
     */
    constructor(client: KintoClientBase, name: string, options?: BucketOptions);
    get execute(): KintoClientBase["execute"];
    get headers(): Record<string, string>;
    /**
     * 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;
    /**
     * Selects a collection.
     *
     * @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.
     * @return {Collection}
     */
    collection(name: string, options?: {
        headers?: Record<string, string>;
        safe?: boolean;
        retry?: number;
    }): Collection;
    /**
     * Retrieves the ETag of the collection 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>}
     */
    getCollectionsTimestamp(options?: {
        headers?: Record<string, string>;
        retry?: number;
    }): Promise<string | null>;
    /**
     * Retrieves the ETag of the group 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>}
     */
    getGroupsTimestamp(options?: {
        headers?: Record<string, string>;
        retry?: number;
    }): Promise<string | null>;
    /**
     * Retrieves bucket 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 bucket data.
     * @param  {Object}  data                    The bucket data object.
     * @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=0]       Number of retries to make
     *     when faced with transient errors.
     * @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 history entries in the current bucket.
     *
     * @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<Array<Object>, Error>}
     */
    listHistory<T>(options?: PaginatedParams & {
        headers?: Record<string, string>;
        retry?: number;
    }): Promise<PaginationResult<HistoryEntry<T>>>;
    /**
     * Retrieves the list of collections in the current bucket.
     *
     * @param  {Object} [options={}]      The options object.
     * @param  {Object} [options.filters={}] The filters 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  {Array}  [options.fields]  Limit response to
     *     just some fields.
     * @return {Promise<Array<Object>, Error>}
     */
    listCollections(options?: PaginatedParams & {
        filters?: Record<string, string | number>;
        headers?: Record<string, string>;
        retry?: number;
        fields?: string[];
    }): Promise<PaginationResult<KintoObject>>;
    /**
     * Creates a new collection in current bucket.
     *
     * @param  {String|undefined}  id          The collection id.
     * @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.permissions] The permissions object.
     * @param  {Object}  [options.data]        The data object.
     * @return {Promise<Object, Error>}
     */
    createCollection(id?: string, options?: {
        safe?: boolean;
        headers?: Record<string, string>;
        retry?: number;
        permissions?: {
            [key in Permission]?: string[];
        };
        data?: any;
    }): Promise<KintoResponse<{}>>;
    /**
     * Deletes a collection from the current bucket.
     *
     * @param  {Object|String} collection              The collection 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>}
     */
    deleteCollection(collection: string | KintoIdObject, options?: {
        headers?: Record<string, string>;
        retry?: number;
        safe?: boolean;
        last_modified?: number;
    }): Promise<KintoResponse<{
        deleted: boolean;
    }>>;
    /**
     * Deletes collections from the current bucket.
     *
     * @param  {Object} [options={}]      The options object.
     * @param  {Object} [options.filters={}] The filters 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  {Array}  [options.fields]  Limit response to
     *     just some fields.
     * @return {Promise<Array<Object>, Error>}
     */
    deleteCollections(options?: PaginatedParams & {
        headers?: Record<string, string>;
        retry?: number;
    }): Promise<PaginationResult<KintoObject>>;
    /**
     * Retrieves the list of groups in the current bucket.
     *
     * @param  {Object} [options={}]      The options object.
     * @param  {Object} [options.filters={}] The filters 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  {Array}  [options.fields]  Limit response to
     *     just some fields.
     * @return {Promise<Array<Object>, Error>}
     */
    listGroups(options?: PaginatedParams & {
        headers?: Record<string, string>;
        retry?: number;
    }): Promise<PaginationResult<Group>>;
    /**
     * Fetches a group in current bucket.
     *
     * @param  {String} id                The group 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  {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.
     * @return {Promise<Object, Error>}
     */
    getGroup(id: string, options?: {
        headers?: Record<string, string>;
        retry?: number;
        query?: {
            [key: string]: string;
        };
        fields?: string[];
    }): Promise<KintoResponse<Group>>;
    /**
     * Creates a new group in current bucket.
     *
     * @param  {String|undefined}  id                    The group id.
     * @param  {Array<String>}     [members=[]]          The list of principals.
     * @param  {Object}            [options={}]          The options object.
     * @param  {Object}            [options.data]        The data object.
     * @param  {Object}            [options.permissions] The permissions 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.
     * @return {Promise<Object, Error>}
     */
    createGroup(id?: string, members?: string[], options?: {
        data?: any;
        permissions?: {
            [key in Permission]?: string[];
        };
        safe?: boolean;
        headers?: Record<string, string>;
        retry?: number;
    }): Promise<KintoResponse<Group>>;
    /**
     * Updates an existing group in current bucket.
     *
     * @param  {Object}  group                   The group object.
     * @param  {Object}  [options={}]            The options object.
     * @param  {Object}  [options.data]          The data object.
     * @param  {Object}  [options.permissions]   The permissions 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  {Number}  [options.last_modified] The last_modified option.
     * @return {Promise<Object, Error>}
     */
    updateGroup<T extends MappableObject>(group: KintoIdObject, options?: {
        data?: T & {
            members?: string[];
        };
        permissions?: {
            [key in Permission]?: string[];
        };
        safe?: boolean;
        headers?: Record<string, string>;
        retry?: number;
        last_modified?: number;
        patch?: boolean;
    }): Promise<KintoResponse<T & {
        members: string[];
    }>>;
    /**
     * Deletes a group from the current bucket.
     *
     * @param  {Object|String} group                   The group 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>}
     */
    deleteGroup(group: string | KintoIdObject, options?: {
        headers?: Record<string, string>;
        retry?: number;
        safe?: boolean;
        last_modified?: number;
    }): Promise<KintoResponse<{
        deleted: boolean;
    }>>;
    /**
     * Deletes groups from the current bucket.
     *
     * @param  {Object} [options={}]          The options object.
     * @param  {Object} [options.filters={}]  The filters 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  {Array}  [options.fields]      Limit response to
     *     just some fields.
     * @return {Promise<Array<Object>, Error>}
     */
    deleteGroups(options?: PaginatedParams & {
        headers?: Record<string, string>;
        retry?: number;
    }): Promise<PaginationResult<KintoObject>>;
    /**
     * Retrieves the list of permissions for this bucket.
     *
     * @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 bucket permissions with the ones provided.
     *
     * @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>}
     */
    setPermissions(permissions: {
        [key in Permission]?: string[];
    }, options?: {
        safe?: boolean;
        headers?: Record<string, string>;
        retry?: number;
        last_modified?: number;
    }): Promise<KintoResponse<{}>>;
    /**
     * Append principals to the bucket 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 bucket 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<{}>>;
    /**
     * Performs batch operations at the current bucket 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=0]    The retry option.
     * @param  {Boolean}  [options.aggregate]  Produces a grouped result object.
     * @return {Promise<Object, Error>}
     */
    batch(fn: (client: Bucket) => void, options?: {
        headers?: Record<string, string>;
        safe?: boolean;
        retry?: number;
        aggregate?: boolean;
    }): Promise<OperationResponse<KintoObject>[] | AggregateResponse>;
}