chore: More type

cozy · Dec 14, 2022 · 7f79c72 · 7f79c72
1 parent d769917
commit 7f79c72
Show file tree

Hide file tree

Showing 3 changed files with 44 additions and 13 deletions.
diff --git 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<JSONAPIDocument>} 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
@@ -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<CozyClientDocument>} data
+ * @property {number} skip
+ * @property {boolean} next
+ * @property {object} [meta]
+ * @property {string} [bookmark]
+ * @property {object} [execution_stats]
+ *
+ * @typedef JSONAPIDocumentForDataRoute
+ * @property {Array<CozyClientDocument>} 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<string>} [options.keys] - Keys to query
-   * @returns {Promise<{data: CozyClientDocument, meta, skip, bookmark, next}>} The JSON API conformant response.
+   * @returns {Promise<JSONAPIDocument>} 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<JSONAPIDocumentForDataRoute & JSONAPIDocument>} 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<object>} - The find response
+   * @returns {Promise<JSONAPIDocumentForDataRoute & JSONAPIDocument>} - 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<JSONAPIDocument>} 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<Array<{data}>>} Documents fetched
+   * @returns {Promise<Array<CozyClientDocument>>} 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<object>}  JsonAPI response containing normalized document as data attribute
+   * @returns {Promise<CozyClientDocument>}  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
@@ -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<import('./DocumentCollection').JSONAPIDocument>} 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<Array<object|IOCozyFolder>>}    The JSON API conformant response.
+   * @returns {Promise<Array<JSONApiFiles>>}    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<object>} documents
+   * @property {Array<object>} results
    * @returns {Promise<FetchChangesReturnValue>}
    */
   async fetchChanges(couchOptions = {}, options = {}) {