From 7f79c729a5b25d43c73fb5ab0f9870ff4640f1d6 Mon Sep 17 00:00:00 2001 From: Crash-- Date: Wed, 14 Dec 2022 15:19:54 +0100 Subject: [PATCH] chore: More type --- .../cozy-stack-client/src/AppCollection.js | 20 +++++++++++--- .../src/DocumentCollection.js | 27 +++++++++++++++---- .../cozy-stack-client/src/FileCollection.js | 10 +++---- 3 files changed, 44 insertions(+), 13 deletions(-) diff --git a/packages/cozy-stack-client/src/AppCollection.js b/packages/cozy-stack-client/src/AppCollection.js index 8f466e4af6..28fe505709 100644 --- a/packages/cozy-stack-client/src/AppCollection.js +++ b/packages/cozy-stack-client/src/AppCollection.js @@ -8,9 +8,17 @@ import Collection from './Collection' import DocumentCollection, { normalizeDoc } from './DocumentCollection' import { FetchError } from './errors' import logger from './logger' - +/** + * @typedef {import('./DocumentCollection').CozyClientDocument} CozyClientDocument + */ export const APPS_DOCTYPE = 'io.cozy.apps' +/** + * + * @param {object} app Doc to normalize + * @param {string} doctype Doctype + * @returns CozyClientDocument document + */ export const normalizeApp = (app, doctype) => { return { ...app.attributes, @@ -28,7 +36,12 @@ class AppCollection extends DocumentCollection { super(APPS_DOCTYPE, stackClient) this.endpoint = '/apps/' } - + /** + * @param {string} idArg + * @param {Array} query + * + * @returns {Promise<{data: CozyClientDocument}>} + */ async get(idArg, query) { let id if (idArg.indexOf('/') > -1) { @@ -88,7 +101,8 @@ class AppCollection extends DocumentCollection { * * The returned documents are not paginated by the stack. * - * @returns {{data, meta, skip, next}} The JSON API conformant response. + * @typedef {import("./DocumentCollection").JSONAPIDocument} JSONAPIDocument + * @returns {Promise} The JSON API conformant response. * @throws {FetchError} */ async all() { diff --git a/packages/cozy-stack-client/src/DocumentCollection.js b/packages/cozy-stack-client/src/DocumentCollection.js index 6fa039d56d..94cd37afc6 100644 --- a/packages/cozy-stack-client/src/DocumentCollection.js +++ b/packages/cozy-stack-client/src/DocumentCollection.js @@ -35,6 +35,22 @@ const DATABASE_DOES_NOT_EXIST = 'Database does not exist.' * @typedef {import('./mangoIndex').MangoPartialFilter} MangoPartialFilter * @typedef {import('./mangoIndex').DesignDoc} DesignDoc * @typedef {import('./errors').FetchError} FetchError + * + * @typedef JSONAPIDocument + * @property {Array} data + * @property {number} skip + * @property {boolean} next + * @property {object} [meta] + * @property {string} [bookmark] + * @property {object} [execution_stats] + * + * @typedef JSONAPIDocumentForDataRoute + * @property {Array} docs + * @property {number} skip + * @property {boolean} next + * @property {object} [meta] + * @property {string} [bookmark] + * @property {object} [execution_stats] */ /** * Normalize a document, adding its doctype if needed @@ -114,7 +130,7 @@ class DocumentCollection { * @param {number} [options.skip=0] - Pagination Skip * @param {string} [options.bookmark] - Pagination bookmark * @param {Array} [options.keys] - Keys to query - * @returns {Promise<{data: CozyClientDocument, meta, skip, bookmark, next}>} The JSON API conformant response. + * @returns {Promise} The JSON API conformant response. * @throws {FetchError} */ async all({ limit = 100, skip = 0, bookmark, keys } = {}) { @@ -184,6 +200,7 @@ class DocumentCollection { * @param {string} path - path to fetch * @param {MangoSelector} selector - selector * @param {MangoQueryOptions} options - request options + * @returns {Promise} documents */ async fetchDocumentsWithMango(path, selector, options = {}) { return this.stackClient.fetchJSON( @@ -270,7 +287,7 @@ class DocumentCollection { * @param {MangoSelector} selector The mango selector * @param {MangoQueryOptions} options The find options * - * @returns {Promise} - The find response + * @returns {Promise} - The find response * @protected */ async findWithMango(path, selector, options = {}) { @@ -301,7 +318,7 @@ The returned documents are paginated by the stack. * * @param {MangoSelector} selector The Mango selector. * @param {MangoQueryOptions} options MangoQueryOptions - * @returns {Promise<{data, skip, bookmark, next, execution_stats}>} The JSON API conformant response. + * @returns {Promise} The JSON API conformant response. * @throws {FetchError} */ async find(selector, options = {}) { @@ -332,7 +349,7 @@ The returned documents are paginated by the stack. * * @param {MangoSelector} selector The Mango selector. * @param {MangoQueryOptions} options MangoQueryOptions - * @returns {Promise>} Documents fetched + * @returns {Promise>} Documents fetched * @throws {FetchError} */ async findAll(selector, options = {}) { @@ -352,7 +369,7 @@ The returned documents are paginated by the stack. * Get a document by id * * @param {string} id The document id. - * @returns {Promise} JsonAPI response containing normalized document as data attribute + * @returns {Promise} JsonAPI response containing normalized document as data attribute */ async get(id) { return Collection.get( diff --git a/packages/cozy-stack-client/src/FileCollection.js b/packages/cozy-stack-client/src/FileCollection.js index cef96991a4..1032a93ffb 100644 --- a/packages/cozy-stack-client/src/FileCollection.js +++ b/packages/cozy-stack-client/src/FileCollection.js @@ -234,7 +234,7 @@ class FileCollection extends DocumentCollection { * * @param {object} selector The Mango selector. * @param {MangoQueryOptions} options The query options - * @returns {Promise<{data, meta, skip, next, bookmark, execution_stats}>} The JSON API conformant response. + * @returns {Promise} The JSON API conformant response. * @throws {FetchError} */ async find(selector, options = {}) { @@ -842,7 +842,7 @@ class FileCollection extends DocumentCollection { * * @private * @param {DirectoryAttributes} attributes - Attributes of the directory - * @returns {Promise} + * @returns {Promise<{data: FileDocument}>} * @throws {Error} - explaining reason why creation failed */ async createDirectory(attributes) { @@ -1116,9 +1116,9 @@ class FileCollection extends DocumentCollection { * @param {number} [options.skip] For skip-based pagination, the number of referenced files to skip. * @param {number} [options.limit] For pagination, the number of results to return. * @param {CouchDBViewCursor} [options.cursor] For cursor-based pagination, the index cursor. - * @param {boolean} options.includeFiles Include the whole file documents in the results list + * @param {boolean} [options.includeFiles] Include the whole file documents in the results list * - * @returns {Promise>} The JSON API conformant response. + * @returns {Promise>} The JSON API conformant response. */ async findNotSynchronizedDirectories( oauthClient, @@ -1219,7 +1219,7 @@ class FileCollection extends DocumentCollection { * @typedef {object} FetchChangesReturnValue * @property {string} newLastSeq * @property {boolean} pending - * @property {Array} documents + * @property {Array} results * @returns {Promise} */ async fetchChanges(couchOptions = {}, options = {}) {