kinto/lib/adapters/IDB.d.ts

An Offline-First JavaScript client for Kinto.

import BaseAdapter, { StorageProxy } from "./base";
import { RecordStatus } from "../types";
import { KintoObject } from "../http";
/**
 * Small helper that wraps the opening of an IndexedDB into a Promise.
 *
 * @param dbname          {String}   The database name.
 * @param version         {Integer}  Schema version
 * @param onupgradeneeded {Function} The callback to execute if schema is
 *                                   missing or different.
 * @return {Promise<IDBDatabase>}
 */
export declare function open(dbname: string, { version, onupgradeneeded, }: {
    version?: number;
    onupgradeneeded: (event: IDBVersionChangeEvent) => void;
}): Promise<IDBDatabase>;
/**
 * Helper to run the specified callback in a single transaction on the
 * specified store.
 * The helper focuses on transaction wrapping into a promise.
 *
 * @param db           {IDBDatabase} The database instance.
 * @param name         {String}      The store name.
 * @param callback     {Function}    The piece of code to execute in the transaction.
 * @param options      {Object}      Options.
 * @param options.mode {String}      Transaction mode (default: read).
 * @return {Promise} any value returned by the callback.
 */
export declare function execute(db: IDBDatabase, name: string, callback: (store: IDBObjectStore, abort?: (...args: any[]) => any) => any, options?: {
    mode?: IDBTransactionMode;
}): Promise<unknown>;
declare class IDBError extends Error {
    constructor(method: string, err: Error);
}
/**
 * IndexedDB adapter.
 *
 * This adapter doesn't support any options.
 */
export default class IDB<B extends {
    id: string;
    last_modified?: number;
    _status?: RecordStatus;
}> extends BaseAdapter<B> {
    private _db;
    cid: string;
    dbName: string;
    private _options;
    static get IDBError(): typeof IDBError;
    /**
     * Constructor.
     *
     * @param  {String} cid  The key base for this collection (eg. `bid/cid`)
     * @param  {Object} options
     * @param  {String} options.dbName         The IndexedDB name (default: `"KintoDB"`)
     * @param  {String} options.migrateOldData Whether old database data should be migrated (default: `false`)
     */
    constructor(cid: string, options?: {
        dbName?: string;
        migrateOldData?: boolean;
    });
    _handleError(method: string, err: Error): void;
    /**
     * Ensures a connection to the IndexedDB database has been opened.
     *
     * @override
     * @return {Promise}
     */
    open(): Promise<this>;
    /**
     * Closes current connection to the database.
     *
     * @override
     * @return {Promise}
     */
    close(): Promise<void>;
    /**
     * Returns a transaction and an object store for a store name.
     *
     * To determine if a transaction has completed successfully, we should rather
     * listen to the transaction’s complete event rather than the IDBObjectStore
     * request’s success event, because the transaction may still fail after the
     * success event fires.
     *
     * @param  {String}      name  Store name
     * @param  {Function}    callback to execute
     * @param  {Object}      options Options
     * @param  {String}      options.mode  Transaction mode ("readwrite" or undefined)
     * @return {Object}
     */
    prepare(name: string, callback: (store: IDBObjectStore, abort?: (...args: any[]) => any) => any, options?: {
        mode?: IDBTransactionMode;
    }): Promise<void>;
    /**
     * Deletes every records in the current collection.
     *
     * @override
     * @return {Promise}
     */
    clear(): Promise<void>;
    /**
     * Executes the set of synchronous CRUD operations described in the provided
     * callback within an IndexedDB transaction, for current db store.
     *
     * The callback will be provided an object exposing the following synchronous
     * CRUD operation methods: get, create, update, delete.
     *
     * Important note: because limitations in IndexedDB implementations, no
     * asynchronous code should be performed within the provided callback; the
     * promise will therefore be rejected if the callback returns a Promise.
     *
     * Options:
     * - {Array} preload: The list of record IDs to fetch and make available to
     *   the transaction object get() method (default: [])
     *
     * @example
     * const db = new IDB("example");
     * const result = await db.execute(transaction => {
     *   transaction.create({id: 1, title: "foo"});
     *   transaction.update({id: 2, title: "bar"});
     *   transaction.delete(3);
     *   return "foo";
     * });
     *
     * @override
     * @param  {Function} callback The operation description callback.
     * @param  {Object}   options  The options object.
     * @return {Promise}
     */
    execute<T>(callback: (proxy: StorageProxy<B>) => T, options?: {
        preload: string[];
    }): Promise<T>;
    /**
     * Retrieve a record by its primary key from the IndexedDB database.
     *
     * @override
     * @param  {String} id The record id.
     * @return {Promise}
     */
    get(id: string): Promise<B | null>;
    /**
     * Lists all records from the IndexedDB database.
     *
     * @override
     * @param  {Object} params  The filters and order to apply to the results.
     * @return {Promise}
     */
    list(params?: {
        filters: {
            [key: string]: any;
        };
        order?: string;
    }): Promise<KintoObject[]>;
    /**
     * Store the lastModified value into metadata store.
     *
     * @override
     * @param  {Number}  lastModified
     * @return {Promise}
     */
    saveLastModified(lastModified: number): Promise<number | null>;
    /**
     * Retrieve saved lastModified value.
     *
     * @override
     * @return {Promise}
     */
    getLastModified(): Promise<number | null>;
    /**
     * Load a dump of records exported from a server.
     *
     * @deprecated Use {@link importBulk} instead.
     * @abstract
     * @param  {Array} records The records to load.
     * @return {Promise}
     */
    loadDump(records: (B & {
        last_modified: number;
    })[]): Promise<B[]>;
    /**
     * Load records in bulk that were exported from a server.
     *
     * @abstract
     * @param  {Array} records The records to load.
     * @return {Promise}
     */
    importBulk(records: (B & {
        last_modified: number;
    })[]): Promise<B[]>;
    saveMetadata(metadata: any): Promise<any>;
    getMetadata(): Promise<any>;
}
export {};