chore: fix JSDoc warning and improve JSDoc

Author: danivek

lib/JSONAPISerializer.js

@@ -27,7 +27,7 @@ const { validateOptions, validateDynamicTypeOptions, validateError } = require('
  * const serializer = new JSONAPISerializer();
  *
  * @class JSONAPISerializer
- * @param {object} [opts] Global options.
+ * @param {Options} [opts] Global options.
  */
 module.exports = class JSONAPISerializer {
   constructor(opts) {
@@ -49,8 +49,8 @@ module.exports = class JSONAPISerializer {
    *
    * @function JSONAPISerializer#register
    * @param {string} type resource's type.
-   * @param {string|object} [schema='default'] schema name.
-   * @param {object} [options] options.
+   * @param {string|Options} [schema='default'] schema name.
+   * @param {Options} [options] options.
    */
   register(type, schema, options) {
     if (typeof schema === 'object') {
@@ -71,13 +71,13 @@ module.exports = class JSONAPISerializer {
    *
    * @see {@link http://jsonapi.org/format/#document-top-level}
    * @function JSONAPISerializer#serialize
-   * @param {string|object} type resource's type as string or a dynamic type options as object.
+   * @param {string|DynamicTypeOptions} type resource's type as string or a dynamic type options as object.
    * @param {object|object[]} data input data.
    * @param {string|object} [schema='default'] resource's schema name.
    * @param {object} [extraData] additional data that can be used in topLevelMeta options.
    * @param {boolean} [excludeData] boolean that can be set to exclude the `data` property in serialized data.
-   * @param {object} [overrideSchemaOptions=] additional schema options, a map of types with options to override
-   * @returns {object} serialized data.
+   * @param {object} [overrideSchemaOptions={}] additional schema options, a map of types with options to override.
+   * @returns {object|object[]} serialized data.
    */
   serialize(type, data, schema, extraData, excludeData, overrideSchemaOptions = {}) {
     // Support optional arguments (schema)
@@ -155,12 +155,12 @@ module.exports = class JSONAPISerializer {
    *
    * @see {@link http://jsonapi.org/format/#document-top-level}
    * @function JSONAPISerializer#serializeAsync
-   * @param {string|object} type resource's type or an object with a dynamic type resolved from data..
+   * @param {string|DynamicTypeOptions} type resource's type as string or a dynamic type options as object.
    * @param {object|object[]} data input data.
    * @param {string} [schema='default'] resource's schema name.
    * @param {object} [extraData] additional data that can be used in topLevelMeta options.
    * @param {boolean} [excludeData] boolean that can be set to exclude the `data` property in serialized data.
-   * @param {object} [overrideSchemaOptions=] additional schema options, a map of types with options to override
+   * @param {object} [overrideSchemaOptions={}] additional schema options, a map of types with options to override.
    * @returns {Promise} resolves with serialized data.
    */
   serializeAsync(type, data, schema, extraData, excludeData, overrideSchemaOptions = {}) {
@@ -280,7 +280,7 @@ module.exports = class JSONAPISerializer {
    * Input data can be a simple object or an array of objects.
    *
    * @function JSONAPISerializer#deserialize
-   * @param {string|object} type resource's type as string or an object with a dynamic type resolved from data.
+   * @param {string|DynamicTypeOptions} type resource's type as string or a dynamic type options as object.
    * @param {object} data JSON API input data.
    * @param {string} [schema='default'] resource's schema name.
    * @returns {object} deserialized data.
@@ -318,7 +318,7 @@ module.exports = class JSONAPISerializer {
    * Input data can be a simple object or an array of objects.
    *
    * @function JSONAPISerializer#deserializeAsync
-   * @param {string|object} type resource's type as string or an object with a dynamic type resolved from data.
+   * @param {string|DynamicTypeOptions} type resource's type as string or a dynamic type options as object.
    * @param {object} data JSON API input data.
    * @param {string} [schema='default'] resource's schema name.
    * @returns {Promise} resolves with serialized data.
@@ -404,7 +404,8 @@ module.exports = class JSONAPISerializer {
    * Input data must be a simple object.
    *
    * @function JSONAPISerializer#deserializeResource
-   * @param {string|object} type resource's type as string or an object with a dynamic type resolved from data.
+   * @private
+   * @param {string|DynamicTypeOptions} type resource's type as string or an object with a dynamic type resolved from data.
    * @param {object} data JSON API resource data.
    * @param {string} [schema='default'] resource's schema name.
    * @param {Map<string, object>} included Included resources.
@@ -529,6 +530,18 @@ module.exports = class JSONAPISerializer {
     return deserializedData;
   }
 
+  /**
+   * Deserialize included
+   *
+   * @function JSONAPISerializer#deserializeIncluded
+   * @private
+   * @param {string} type resource's type as string or an object with a dynamic type resolved from data.
+   * @param {string} id identifier of the resource.
+   * @param {RelationshipOptions} relationshipOpts relationship option.
+   * @param {Map<string, object>} included Included resources.
+   * @param {string[]} lineage resource identifiers already deserialized to prevent circular references.
+   * @returns {object} deserialized data.
+   */
   deserializeIncluded(type, id, relationshipOpts, included, lineage) {
     const includedResource = included.find(
       (resource) => resource.type === type && resource.id === id
@@ -555,10 +568,10 @@ module.exports = class JSONAPISerializer {
    * @private
    * @param {string} type resource's type.
    * @param {object|object[]} data input data.
-   * @param {object} options resource's configuration options.
+   * @param {Options} options resource's configuration options.
    * @param {Map<string, object>} [included] Included resources.
    * @param {object} [extraData] additional data.
-   * @param {object} [overrideSchemaOptions=] additional schema options, a map of types with options to override
+   * @param {object} [overrideSchemaOptions={}] additional schema options, a map of types with options to override.
    * @returns {object|object[]} serialized data.
    */
   serializeResource(type, data, options, included, extraData, overrideSchemaOptions = {}) {
@@ -599,11 +612,11 @@ module.exports = class JSONAPISerializer {
    * @see {@link http://jsonapi.org/format/#document-resource-objects}
    * @function JSONAPISerializer#serializeMixedResource
    * @private
-   * @param {object} typeOption a dynamic type options.
+   * @param {DynamicTypeOptions} typeOption a dynamic type options.
    * @param {object|object[]} data input data.
    * @param {Map<string, object>} [included] Included resources.
    * @param {object} [extraData] additional data.
-   * @param {object} [overrideSchemaOptions=] additional schema options, a map of types with options to override
+   * @param {object} [overrideSchemaOptions={}] additional schema options, a map of types with options to override.
    * @returns {object|object[]} serialized data.
    */
   serializeMixedResource(typeOption, data, included, extraData, overrideSchemaOptions = {}) {
@@ -646,7 +659,7 @@ module.exports = class JSONAPISerializer {
    * @function JSONAPISerializer#serializeAttributes
    * @private
    * @param {object|object[]} data input data.
-   * @param {object} options resource's configuration options.
+   * @param {Options} options resource's configuration options.
    * @returns {object} serialized attributes.
    */
   serializeAttributes(data, options) {
@@ -685,10 +698,10 @@ module.exports = class JSONAPISerializer {
    * @function JSONAPISerializer#serializeRelationships
    * @private
    * @param {object|object[]} data input data.
-   * @param {object} options resource's configuration options.
+   * @param {Options} options resource's configuration options.
    * @param {Map<string, object>} [included]  Included resources.
    * @param {object} [extraData] additional data.
-   * @param {object} [overrideSchemaOptions=] additional schema options, a map of types with options to override
+   * @param {object} [overrideSchemaOptions={}] additional schema options, a map of types with options to override.
    * @returns {object} serialized relationships.
    */
   serializeRelationships(data, options, included, extraData, overrideSchemaOptions = {}) {
@@ -746,7 +759,7 @@ module.exports = class JSONAPISerializer {
    * @param {Map<string, object>} [included] Included resources.
    * @param {object} [data] the entire resource's data.
    * @param {object} [extraData] additional data.
-   * @param {object} [overrideSchemaOptions=] additional schema options, a map of types with options to override
+   * @param {object} [overrideSchemaOptions={}] additional schema options, a map of types with options to override.
    * @returns {object|object[]} serialized relationship data.
    */
   serializeRelationship(
@@ -957,3 +970,42 @@ module.exports = class JSONAPISerializer {
     return data;
   }
 };
+
+/**
+ * @typedef {object} Options
+ * @property {string} [id='id'] the key to use as the reference. Default = 'id'
+ * @property {string[]} [blacklist=[]] an array of blacklisted attributes. Default = []
+ * @property {string[]} [whitelist=[]] an array of whitelisted attributes. Default = []
+ * @property {boolean} [jsonapiObject=true] enable/Disable JSON API Object. Default = true
+ * @property {Function|object} [links] describes the links inside data
+ * @property {Function|object} [topLevelLinks] describes the top-level links
+ * @property {Function|object} [topLevelMeta] describes the top-level meta
+ * @property {Function|object} [meta] describes resource-level meta
+ * @property {object.<string, RelationshipOptions>} [relationships] an object defining some relationships
+ * @property {string[]} [blacklistOnDeserialize=[]] an array of blacklisted attributes. Default = []
+ * @property {string[]} [whitelistOnDeserialize=[]] an array of whitelisted attributes. Default = []
+ * @property {('kebab-case'|'snake_case'|'camelCase')} [convertCase] case conversion for serializing data
+ * @property {('kebab-case'|'snake_case'|'camelCase')} [unconvertCase] case conversion for deserializing data
+ * @property {number} [convertCaseCacheSize=5000] When using convertCase, a LRU cache is utilized for optimization. The default size of the cache is 5000 per conversion type.
+ * @property {Function} [beforeSerialize] a function to transform data before serialization.
+ * @property {Function} [afterDeserialize] a function to transform data after deserialization.
+ */
+
+/**
+ * @typedef {object} RelationshipOptions
+ * @property {string|Function} type a string or a function for the type to use for serializing the relationship (type need to be register)
+ * @property {string} [alternativeKey] an alternative key (string or path) to use if relationship key not exist (example: 'author_id' as an alternative key for 'author' relationship)
+ * @property {string} [schema] a custom schema for serializing the relationship. If no schema define, it use the default one.
+ * @property {Function|object} [links] describes the links for the relationship
+ * @property {Function|object} [meta] describes meta that contains non-standard meta-information about the relationship
+ * @property {Function} [deserialize] describes the function which should be used to deserialize a related property which is not included in the JSON:API document
+ */
+
+/**
+ *
+ * @typedef {object} DynamicTypeOptions
+ * @property {string} id a string for the path to the key to use to determine type or a function deriving a type-string from each data-item.
+ * @property {boolean} [jsonapiObject=true] enable/Disable JSON API Object.
+ * @property {Function|object} [topLevelLinks] describes the top-level links
+ * @property {Function|object} [topLevelMeta] describes the top-level meta.
+ */

lib/validator.js

@@ -173,8 +173,8 @@ function validateError(err) {
    * @throws Will throw an error if the argument is not an object
    * @throws Will throw an error if the argument contains unpermitted members
    * @throws Will throw an error if `links.about` is present but not a string
-   * @param {object} linksObj
-   * @returns {object}
+   * @param {object} linksObj links object
+   * @returns {object} validated links
    */
   const isValidLink = function isValidLink(linksObj) {
     const permittedMembers = ['about'];
@@ -211,12 +211,12 @@ function validateError(err) {
    * @function isValidSource
    * @private
    * @see https://jsonapi.org/format/#error-objects
-   * @param {object} sourceObj
+   * @param {object} sourceObj source object
    * @throws Will throw an error if the argument is not an object
    * @throws Will throw an error if the argument contains unpermitted members
    * @throws Will throw an error if `sourceObj.pointer` is present but not a string
    * @throws Will throw an error if `sourceObj.parameter` is present but not a string
-   * @returns {object}
+   * @returns {object} validated source
    */
   const isValidSource = function isValidSource(sourceObj) {
     const permittedMembers = ['pointer', 'parameter'];
@@ -252,9 +252,9 @@ function validateError(err) {
    * @function isValidMeta
    * @private
    * @see https://jsonapi.org/format/#error-objects
-   * @param {object} metaObj
+   * @param {object} metaObj meta object
    * @throws Will throw an error if the argument is not an object
-   * @returns {object}
+   * @returns {object} validated meta
    */
   const isValidMeta = function isValidMeta(metaObj) {
     if (typeof metaObj !== 'object') {
@@ -271,7 +271,7 @@ function validateError(err) {
    * @private
    * @see https://jsonapi.org/format/#error-objects
    * @param {number} theStatusCode The status code to validate
-   * @returns {boolean}
+   * @returns {boolean} is valid
    */
   const isValidHttpStatusCode = function isValidHttpStatusCode(theStatusCode) {
     const validHttpStatusCodes = [
@@ -306,10 +306,10 @@ function validateError(err) {
    * @function isValidStatus
    * @private
    * @see https://jsonapi.org/format/#error-objects
-   * @param {string|number} theStatusCode
+   * @param {string|number} theStatusCode status code
    * @throws Will throw an error if the argument is not number-like
    * @throws Will throw an error if the argument is not a valid HTTP status code
-   * @returns {string}
+   * @returns {string} validated status
    */
   const isValidStatus = function isValidStatus(theStatusCode) {
     const statusAsNumber = Number(theStatusCode);