cozy-pouch-link 48.25.0 → 49.1.0

package/types/CozyPouchLink.d.ts

@@ -0,0 +1,228 @@
+export function getReplicationURL(uri: any, token: any, doctype: any): string;
+export function isExpiredTokenError(pouchError: any): boolean;
+export default PouchLink;
+export type CozyClientDocument = any;
+export type ReplicationStatus = "idle" | "replicating";
+export type PouchLinkOptions = {
+    /**
+     * Milliseconds between replications
+     */
+    replicationInterval?: number;
+    /**
+     * Doctypes to replicate
+     */
+    doctypes: string[];
+    /**
+     * 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")
+     */
+    doctypesReplicationOptions: Record<string, object>;
+    /**
+     * Platform specific adapters and methods
+     */
+    platform: import('./types').LinkPlatform;
+};
+/**
+ * @typedef {import('cozy-client/src/types').CozyClientDocument} CozyClientDocument
+ *
+ * @typedef {"idle"|"replicating"} ReplicationStatus
+ */
+/**
+ * @typedef {object} PouchLinkOptions
+ * @property {number} [replicationInterval] Milliseconds between replications
+ * @property {string[]} doctypes Doctypes to replicate
+ * @property {Record<string, object>} doctypesReplicationOptions 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")
+ * @property {import('./types').LinkPlatform} platform Platform specific adapters and methods
+ */
+/**
+ * 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.
+ */
+declare class PouchLink extends CozyLink {
+    /**
+     * Return the PouchDB adapter name.
+     * Should be IndexedDB for newest adapters.
+     *
+     * @param {import('./types').LocalStorage} localStorage Methods to access local storage
+     * @returns {Promise<string>} The adapter name
+     */
+    static getPouchAdapterName: (localStorage: import('./types').LocalStorage) => Promise<string>;
+    /**
+     * constructor - Initializes a new PouchLink
+     *
+     * @param {PouchLinkOptions} [opts={}]
+     */
+    constructor(opts?: PouchLinkOptions);
+    options: {
+        replicationInterval: number;
+    } & PouchLinkOptions;
+    doctypes: string[];
+    doctypesReplicationOptions: Record<string, any>;
+    indexes: {};
+    storage: PouchLocalStorage;
+    /** @type {Record<string, ReplicationStatus>} - Stores replication states per doctype */
+    replicationStatus: Record<string, ReplicationStatus>;
+    getReplicationURL(doctype: any): string;
+    registerClient(client: any): Promise<void>;
+    client: any;
+    /**
+     * Migrate the current adapter
+     *
+     * @typedef {object} MigrationParams
+     * @property {string} [fromAdapter] - The current adapter type, e.g. 'idb'
+     * @property {string} [toAdapter] - The new adapter type, e.g. 'indexeddb'
+     * @property {string} [url] - The Cozy URL
+     * @property {Array<object>} [plugins] - The PouchDB plugins
+     *
+     * @param {MigrationParams} params - Migration params
+     */
+    migrateAdapter({ fromAdapter, toAdapter, url, plugins }: {
+        /**
+         * - The current adapter type, e.g. 'idb'
+         */
+        fromAdapter?: string;
+        /**
+         * - The new adapter type, e.g. 'indexeddb'
+         */
+        toAdapter?: string;
+        /**
+         * - The Cozy URL
+         */
+        url?: string;
+        /**
+         * - The PouchDB plugins
+         */
+        plugins?: Array<object>;
+    }): Promise<void>;
+    onLogin(): Promise<void>;
+    pouches: PouchManager;
+    /**
+     * 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
+     */
+    handleOnSync(doctypeUpdates: any): void;
+    handleDoctypeSyncStart(doctype: any): void;
+    handleDoctypeSyncEnd(doctype: any): 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
+     *
+     * @public
+     * @returns {void}
+     */
+    public startReplication(): 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
+     *
+     * @public
+     * @returns {void}
+     */
+    public stopReplication(): void;
+    onSyncError(error: any): Promise<void>;
+    getSyncInfo(doctype: any): import("./types").SyncInfo;
+    getPouch(doctype: any): any;
+    supportsOperation(operation: any): boolean;
+    sanitizeJsonApi(data: any): Pick<Pick<any, string | number | symbol>, string | number | symbol>;
+    /**
+     * Retrieve the existing document from Pouch
+     *
+     * @private
+     * @param {*} id - ID of the document to retrieve
+     * @param {*} type - Doctype of the document to retrieve
+     * @param {*} throwIfNotFound - If true the method will throw when the document is not found. Otherwise it will return null
+     * @returns {Promise<CozyClientDocument | null>}
+     */
+    private getExistingDocument;
+    /**
+     *
+     * Check if there is warmup queries for this doctype
+     * and return if those queries are already warmed up or not
+     *
+     * @param {string} doctype - Doctype to check
+     * @returns {Promise<boolean>} the need to wait for the warmup
+     */
+    needsToWaitWarmup(doctype: string): Promise<boolean>;
+    hasIndex(name: any): boolean;
+    /**
+     * Create the PouchDB index if not existing
+     *
+     * @param {Array} fields - Fields to index
+     * @param {object} indexOption - Options for the index
+     * @param {object} [indexOption.partialFilter] - partialFilter
+     * @param {string} [indexOption.indexName] - indexName
+     * @param {string} [indexOption.doctype] - doctype
+     * @returns {Promise<import('./types').PouchDbIndex>}
+     */
+    createIndex(fields: any[], { partialFilter, indexName, doctype }?: {
+        partialFilter: object;
+        indexName: string;
+        doctype: string;
+    }): Promise<import('./types').PouchDbIndex>;
+    /**
+     * Retrieve the PouchDB index if exist, undefined otherwise
+     *
+     * @param {string} doctype - The query's doctype
+     * @param {import('./types').MangoQueryOptions} options - The find options
+     * @param {string} indexName - The index name
+     * @returns {import('./types').PouchDbIndex | undefined}
+     */
+    findExistingIndex(doctype: string, options: import('./types').MangoQueryOptions, indexName: string): import('./types').PouchDbIndex | undefined;
+    /**
+     * Handle index creation if it is missing.
+     *
+     * When an index is missing, we first check if there is one with a different
+     * name but the same definition. If there is none, we create the new index.
+     *
+     * /!\ Warning: this method is similar to DocumentCollection.handleMissingIndex()
+     * If you edit this method, please check if the change is also needed in DocumentCollection
+     *
+     * @param {string} doctype The mango selector
+     * @param {import('./types').MangoQueryOptions} options The find options
+     * @returns {Promise<import('./types').PouchDbIndex>} index
+     * @private
+     */
+    private ensureIndex;
+    executeQuery({ doctype, selector, sort, fields, limit, id, ids, skip, indexedFields, partialFilter }: {
+        doctype: any;
+        selector: any;
+        sort: any;
+        fields: any;
+        limit: any;
+        id: any;
+        ids: any;
+        skip: any;
+        indexedFields: any;
+        partialFilter: any;
+    }): Promise<{
+        data: any;
+        meta?: undefined;
+        skip?: undefined;
+        next?: undefined;
+    } | {
+        data: any;
+        meta: {
+            count: any;
+        };
+        skip: any;
+        next: boolean;
+    }>;
+    executeMutation(mutation: any, result: any, forward: any): Promise<any>;
+    createDocument(mutation: any): Promise<any>;
+    updateDocument(mutation: any): Promise<any>;
+    updateDocuments(mutation: any): Promise<any[]>;
+    deleteDocument(mutation: any): Promise<any>;
+    addReferencesTo(mutation: any): Promise<void>;
+    dbMethod(method: any, mutation: any): Promise<any>;
+    syncImmediately(): Promise<void>;
+}
+import { CozyLink } from "cozy-client";
+import { PouchLocalStorage } from "./localStorage";
+import PouchManager from "./PouchManager";

package/types/PouchManager.d.ts

@@ -0,0 +1,86 @@
+export default PouchManager;
+/**
+ * Handles the lifecycle of several pouches
+ *
+ * - Creates/Destroys the pouches
+ * - Replicates periodically
+ */
+declare class PouchManager {
+    constructor(doctypes: any, options: any);
+    options: any;
+    doctypes: any;
+    storage: PouchLocalStorage;
+    PouchDB: any;
+    isOnline: any;
+    events: any;
+    init(): Promise<void>;
+    pouches: import("lodash").Dictionary<any>;
+    /** @type {Record<string, import('./types').SyncInfo>} - Stores synchronization info per doctype */
+    syncedDoctypes: Record<string, import('./types').SyncInfo>;
+    warmedUpQueries: any;
+    getReplicationURL: any;
+    doctypesReplicationOptions: any;
+    listenerLaunched: boolean;
+    ensureDatabasesExistDone: boolean;
+    /**
+     * Starts periodic syncing of the pouches
+     *
+     * @returns {Promise<Loop | void>}
+     */
+    startReplicationLoop(): Promise<Loop | void>;
+    /** Stop periodic syncing of the pouches */
+    stopReplicationLoop(): void;
+    /** Starts replication */
+    replicateOnce(): Promise<any>;
+    executeQuery: any;
+    /** @type {import('./types').CancelablePromise[]} - Stores replication promises */
+    replications: import('./types').CancelablePromise[];
+    addListeners(): void;
+    removeListeners(): void;
+    destroy(): Promise<any[]>;
+    /**
+     * 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.
+     */
+    ensureDatabasesExist(): Promise<void>;
+    replicationLoop: Loop;
+    /**
+     * If a replication is currently ongoing, will start a replication
+     * just after it has finished. Otherwise it will start a replication
+     * immediately
+     */
+    syncImmediately(): void;
+    handleReplicationError(err: any): void;
+    cancelCurrentReplications(): void;
+    waitForCurrentReplications(): Promise<void> | Promise<any[]>;
+    getPouch(doctype: any): any;
+    /**
+     * Update the Sync info for the specifed doctype
+     *
+     * @param {string} doctype - The doctype to update
+     * @param {import('./types').SyncStatus} status - The new Sync status for the doctype
+     */
+    updateSyncInfo(doctype: string, status?: import('./types').SyncStatus): Promise<void>;
+    /**
+     * Get the Sync info for the specified doctype
+     *
+     * @param {string} doctype - The doctype to check
+     * @returns {import('./types').SyncInfo}
+     */
+    getSyncInfo(doctype: string): import('./types').SyncInfo;
+    /**
+     * Get the Sync status for the specified doctype
+     *
+     * @param {string} doctype - The doctype to check
+     * @returns {import('./types').SyncStatus}
+     */
+    getSyncStatus(doctype: string): import('./types').SyncStatus;
+    clearSyncedDoctypes(): Promise<void>;
+    warmupQueries(doctype: any, queries: any): Promise<void>;
+    checkToWarmupDoctype(doctype: any, replicationOptions: any): void;
+    areQueriesWarmedUp(doctype: any, queries: any): Promise<any>;
+    clearWarmedUpQueries(): Promise<void>;
+}
+import { PouchLocalStorage } from "./localStorage";
+import Loop from "./loop";

package/types/__tests__/fixtures.d.ts

@@ -0,0 +1,48 @@
+export namespace TODO_1 {
+    const _id: string;
+    const _type: string;
+    const label: string;
+    const done: boolean;
+}
+export namespace TODO_2 {
+    const _id_1: string;
+    export { _id_1 as _id };
+    const _type_1: string;
+    export { _type_1 as _type };
+    const label_1: string;
+    export { label_1 as label };
+    const done_1: boolean;
+    export { done_1 as done };
+}
+export namespace TODO_3 {
+    const _id_2: string;
+    export { _id_2 as _id };
+    const _type_2: string;
+    export { _type_2 as _type };
+    const label_2: string;
+    export { label_2 as label };
+    const done_2: boolean;
+    export { done_2 as done };
+}
+export namespace TODO_4 {
+    const _id_3: string;
+    export { _id_3 as _id };
+    const _type_3: string;
+    export { _type_3 as _type };
+    const label_3: string;
+    export { label_3 as label };
+    const done_3: boolean;
+    export { done_3 as done };
+}
+export namespace SCHEMA {
+    namespace todos {
+        const doctype: string;
+        namespace relationships {
+            namespace attachments {
+                export const type: string;
+                const doctype_1: string;
+                export { doctype_1 as doctype };
+            }
+        }
+    }
+}

package/types/__tests__/mocks.d.ts

@@ -0,0 +1,4 @@
+export function pouchReplication(mockOptions: any): (url: any, options: any) => {
+    on: (event: any, fn: any) => any;
+    cancel: () => void;
+};

package/types/helpers.d.ts

@@ -0,0 +1,17 @@
+export default helpers;
+declare namespace helpers {
+    function isAdapterBugged(adapterName: any): boolean;
+    function withoutDesignDocuments(res: any): any;
+    function getDocs(db: any, fct: any, options?: {}): any;
+    function allDocs(db: any, options?: {}): Promise<any>;
+    function find(db: any, options?: {}): Promise<any>;
+    function isDesignDocument(doc: any): boolean;
+    function isDeletedDocument(doc: any): any;
+    function insertBulkDocs(db: any, docs: any): Promise<any>;
+    function normalizeFindSelector({ selector, sort, indexedFields, partialFilter }: {
+        selector: any;
+        sort: any;
+        indexedFields: any;
+        partialFilter: any;
+    }): any;
+}

package/types/index.d.ts

@@ -0,0 +1 @@
+export { default } from "./CozyPouchLink";

package/types/jsonapi.d.ts

@@ -0,0 +1,19 @@
+export function normalizeDoc(doc: any, doctype: any, client: any): any;
+export function fromPouchResult({ res, withRows, doctype, client }: {
+    res: any;
+    withRows: any;
+    doctype: any;
+    client: any;
+}): {
+    data: any;
+    meta?: undefined;
+    skip?: undefined;
+    next?: undefined;
+} | {
+    data: any;
+    meta: {
+        count: any;
+    };
+    skip: any;
+    next: boolean;
+};

package/types/localStorage.d.ts

@@ -0,0 +1,124 @@
+export const LOCALSTORAGE_SYNCED_KEY: "cozy-client-pouch-link-synced";
+export const LOCALSTORAGE_WARMUPEDQUERIES_KEY: "cozy-client-pouch-link-warmupedqueries";
+export const LOCALSTORAGE_LASTSEQUENCES_KEY: "cozy-client-pouch-link-lastreplicationsequence";
+export const LOCALSTORAGE_LASTREPLICATEDDOCID_KEY: "cozy-client-pouch-link-lastreplicateddocid";
+export const LOCALSTORAGE_ADAPTERNAME: "cozy-client-pouch-link-adaptername";
+export class PouchLocalStorage {
+    constructor(storageEngine: any);
+    storageEngine: any;
+    /**
+     * Persist the last replicated doc id for a doctype
+     *
+     * @param {string} doctype - The replicated doctype
+     * @param {string} id - The docid
+     *
+     * @returns {Promise<void>}
+     */
+    persistLastReplicatedDocID(doctype: string, id: string): Promise<void>;
+    /**
+     * @returns {Promise<Record<string, string>>}
+     */
+    getAllLastReplicatedDocID(): Promise<Record<string, string>>;
+    /**
+     * Get the last replicated doc id for a doctype
+     *
+     * @param {string} doctype - The doctype
+     * @returns {Promise<string>} The last replicated docid
+     */
+    getLastReplicatedDocID(doctype: string): Promise<string>;
+    /**
+     * Destroy all the replicated doc id
+     *
+     * @returns {Promise<void>}
+     */
+    destroyAllLastReplicatedDocID(): Promise<void>;
+    /**
+     * Persist the synchronized doctypes
+     *
+     * @param {Record<string, import("./types").SyncInfo>} syncedDoctypes - The sync doctypes
+     *
+     * @returns {Promise<void>}
+     */
+    persistSyncedDoctypes(syncedDoctypes: Record<string, import("./types").SyncInfo>): Promise<void>;
+    /**
+     * Get the persisted doctypes
+     *
+     * @returns {Promise<object>} The synced doctypes
+     */
+    getPersistedSyncedDoctypes(): Promise<object>;
+    /**
+     * Destroy the synced doctypes
+     *
+     * @returns {Promise<void>}
+     */
+    destroySyncedDoctypes(): Promise<void>;
+    /**
+     * Persist the last CouchDB sequence for a synced doctype
+     *
+     * @param {string} doctype - The synced doctype
+     * @param {string} sequence - The sequence hash
+     *
+     * @returns {Promise<void>}
+     */
+    persistDoctypeLastSequence(doctype: string, sequence: string): Promise<void>;
+    /**
+     * @returns {Promise<object>}
+     */
+    getAllLastSequences(): Promise<object>;
+    /**
+     * Get the last CouchDB sequence for a doctype
+     *
+     * @param {string} doctype - The doctype
+     *
+     * @returns {Promise<string>} the last sequence
+     */
+    getDoctypeLastSequence(doctype: string): Promise<string>;
+    /**
+     * Destroy all the last sequence
+     *
+     * @returns {Promise<void>}
+     */
+    destroyAllDoctypeLastSequence(): Promise<void>;
+    /**
+     * Destroy the last sequence for a doctype
+     *
+     * @param {string} doctype - The doctype
+     *
+     * @returns {Promise<void>}
+     */
+    destroyDoctypeLastSequence(doctype: string): Promise<void>;
+    /**
+     * Persist the warmed up queries
+     *
+     * @param {object} warmedUpQueries - The warmedup queries
+     *
+     * @returns {Promise<void>}
+     */
+    persistWarmedUpQueries(warmedUpQueries: object): Promise<void>;
+    /**
+     * Get the warmed up queries
+     *
+     * @returns {Promise<object>} the warmed up queries
+     */
+    getPersistedWarmedUpQueries(): Promise<object>;
+    /**
+     * Destroy the warmed queries
+     *
+     * @returns {Promise<void>}
+     */
+    destroyWarmedUpQueries(): Promise<void>;
+    /**
+     * Get the adapter name
+     *
+     * @returns {Promise<string>} The adapter name
+     */
+    getAdapterName(): Promise<string>;
+    /**
+     * Persist the adapter name
+     *
+     * @param {string} adapter - The adapter name
+     *
+     * @returns {Promise<void>}
+     */
+    persistAdapterName(adapter: string): Promise<void>;
+}

package/types/logger.d.ts

@@ -0,0 +1,2 @@
+export default logger;
+declare const logger: any;

package/types/loop.d.ts

@@ -0,0 +1,60 @@
+export default Loop;
+/**
+ * Utility to call a function (task) periodically
+ * and on demand immediately.
+ *
+ * Public API
+ *
+ * - start
+ * - stop
+ * - scheduleImmediateTask
+ * - waitForCurrentTask
+ */
+declare class Loop {
+    constructor(task: any, delay: any, _afterRound: any, _sleep: any);
+    task: any;
+    delay: any;
+    /**
+     * 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.
+     */
+    round(): Promise<void>;
+    immediateTasks: any[];
+    started: boolean;
+    afterRound: any;
+    sleep: any;
+    /**
+     * Starts the loop. Will run the task periodically each `this.delay` ms.
+     * Ignores multiple starts.
+     */
+    start(): void;
+    /**
+     * Stops the loop, clears immediate tasks.
+     * Cancels current task if possible
+     */
+    stop(): void;
+    waitForCurrent(): Promise<void>;
+    /**
+     * Flushes the immediate tasks list and calls each task.
+     * Each task is awaited before the next is started.
+     */
+    runImmediateTasks(): Promise<void>;
+    /**
+     * 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.
+     *
+     * @param  {Function} task - Optional custom function to be run immediately
+     */
+    scheduleImmediateTask(task?: Function): Promise<void>;
+    clearImmediateTasks(): void;
+    /**
+     * Calls and saves current task.
+     * Stops loop in case of error of the task.
+     */
+    runTask(task: any): Promise<void>;
+    currentTask: any;
+    _rounding: boolean;
+    timeout: NodeJS.Timeout;
+}

package/types/mango.d.ts

@@ -0,0 +1,3 @@
+export function makeKeyFromPartialFilter(condition: object): string;
+export function getIndexNameFromFields(fields: Array<string>, partialFilter?: object): string;
+export function getIndexFields({ selector, sort, partialFilter }: import('./types').MangoQueryOptions): string[];

package/types/migrations/adapter.d.ts

@@ -0,0 +1,18 @@
+export function migratePouch({ dbName, fromAdapter, toAdapter }: MigrationParams): Promise<object>;
+/**
+ * Migrate a PouchDB database to a new adapter.
+ */
+export type MigrationParams = {
+    /**
+     * - The database name
+     */
+    dbName?: string;
+    /**
+     * - The current adapter type, e.g. 'idb'
+     */
+    fromAdapter?: string;
+    /**
+     * - The new adapter type, e.g. 'indexeddb'
+     */
+    toAdapter?: string;
+};

package/types/platformWeb.d.ts

@@ -0,0 +1,17 @@
+export namespace platformWeb {
+    export { storage };
+    export { events };
+    export { PouchDB as pouchAdapter };
+    export { isOnline };
+}
+declare namespace storage {
+    function getItem(key: any): Promise<string>;
+    function setItem(key: any, value: any): Promise<void>;
+    function removeItem(key: any): Promise<void>;
+}
+declare namespace events {
+    function addEventListener(eventName: any, handler: any): void;
+    function removeEventListener(eventName: any, handler: any): void;
+}
+declare function isOnline(): Promise<boolean>;
+export {};

package/types/remote.d.ts

@@ -0,0 +1,6 @@
+export const DATABASE_NOT_FOUND_ERROR: "Database does not exist";
+export const DATABASE_RESERVED_DOCTYPE_ERROR: "Reserved doctype";
+export function isDatabaseNotFoundError(error: any): boolean;
+export function isDatabaseUnradableError(error: any): boolean;
+export function fetchRemoteInstance(url: URL, params?: object): Promise<object>;
+export function fetchRemoteLastSequence(baseUrl: string): Promise<string>;

package/types/replicateOnce.d.ts

@@ -0,0 +1,29 @@
+export function replicateOnce(pouchManager: import('./PouchManager').default): Promise<any>;
+export type FulfilledPromise = {
+    /**
+     * - The status of the promise
+     */
+    status: 'fulfilled';
+    /**
+     * - The Error rejected by the promise (undefined when fulfilled)
+     */
+    reason: undefined;
+    /**
+     * - The resolved value of the promise
+     */
+    value: any;
+};
+export type RejectedPromise = {
+    /**
+     * - The status of the promise
+     */
+    status: 'rejected';
+    /**
+     * - The Error rejected by the promise
+     */
+    reason: Error;
+    /**
+     * - The resolved value of the promise (undefined when rejected)
+     */
+    value: undefined;
+};