Add data and extra data to all functions in a schema (#27) (#28)

Add data and extra data to all functions in a schema (#27)

Author: danivek

Diff for: README.md

@@ -28,15 +28,23 @@ Serializer.register(type, options);
 - **id** (optional): The key to use as the reference. Default = 'id'.
 - **blacklist** (optional): An array of blacklisted attributes. Default = [].
 - **whitelist** (optional): An array of whitelisted attributes. Default = [].
-- **links** (optional): An *object* or a *function* that describes the links inside data. (If it is an object values can be string or function).
-- **topLevelMeta** (optional): An *object* or a *function* that describes the top-level meta. (If it is an object values can be string or function).
-- **topLevelLinks** (optional): An *object* or a *function* that describes the top-level links. (If it is an object values can be string or function).
+- **links** (optional): Describes the links inside data. It can be:
+    - An *object* (values can be string or function).
+    - A *function* with one argument `function(data) { ... }` or with two arguments `function(data, extraData) { ... }`
+- **topLevelMeta** (optional): Describes the top-level meta. It can be:
+    - An *object* (values can be string or function).
+    - A *function* with one argument `function(extraData) { ... }` or with two arguments `function(data, extraData) { ... }`
+- **topLevelLinks** (optional): Describes the top-level links. It can be:
+    - An *object* (values can be string or function).
+    - A *function* with one argument `function(extraData) { ... }` or with two arguments `function(data, extraData) { ... }`
 - **relationships** (optional): An object defining some relationships
     - relationship: The property in data to use as a relationship
         - **type**: The type to use for serializing the relationship (type need to be register)
         - **alternativeKey** (optional): An alternative key to use if relationship key not exist (example: 'author_id' as an alternative key for 'author' relationship). See [issue #12](https://github.com/danivek/json-api-serializer/issues/12).
         - **schema** (optional): A custom schema for serializing the relationship. If no schema define, it use the default one.
-        - **links** (optional): An *object* or a *function* that describes the links for the relationship. (If it is an object values can be string or function).
+        - **links** (optional): Describes the links for the relationship. It can be:
+            - An *object* (values can be string or function).
+            - A *function* with one argument `function(data) { ... }` or with two arguments `function(data, extraData) { ... }`
 - **convertCase** (optional): Case conversion for serializing data. Value can be : `kebab-case`, `snake_case`, `camelCase`
 
 **Deserialization options:**
@@ -53,7 +61,7 @@ To avoid repeating the same options for each type, it's possible to add global o
 var JSONAPISerializer = require('json-api-serializer');
 var Serializer = new JSONAPISerializer({
   convertCase: 'kebab-case',
-  unconvertCase: 'caseCase'
+  unconvertCase: 'camelCase'
 });
 ```
 
@@ -130,14 +138,14 @@ Serializer.register('article', {
       schema: 'only-body' // A custom schema
     }
   },
-  topLevelMeta: function(extraOptions) { // An object or a function that describes top level meta.
+  topLevelMeta: function(data, extraData) { // An object or a function that describes top level meta.
     return {
-      count: extraOptions.count,
-      total: extraOptions.total
+      count: extraData.count,
+      total: data.length
     }
   },
   topLevelLinks: { // An object or a function that describes top level links.
-    self: '/articles' // Can be a function (with extra options argument) or a string value
+    self: '/articles' // Can be a function (with extra data argument) or a string value
   }
 });
 
@@ -169,7 +177,7 @@ Serializer.register('comment', 'only-body', {
 
 ### Serialize
 
-Serialize it with the corresponding resource type, data and optional extra options :
+Serialize it with the corresponding resource type, data and optional extra data :
 
 ```javascript
 // Synchronously (blocking)
@@ -189,7 +197,8 @@ The output data will be :
     "version": "1.0"
   },
   "meta": {
-    "count": 2
+    "count": 2,
+    "total": 1
   },
   "links": {
     "self": "/articles"
@@ -360,8 +369,8 @@ Example :
 ```javascript
 relationships: {
   comments: {
-  type: 'comment'
-  schema: 'customSchema'
+    type: 'comment'
+    schema: 'customSchema'
   }
 }
 ```
@@ -371,8 +380,12 @@ relationships: {
 If your data contains one or multiple objects of varying types, it's possible to define a configuration object instead of the type-string as the first argument of ```serialize``` and ```serializeAsync``` with these options:
 
 - **type** (required): A *string* for the path to the key to use to determine type or a *function* deriving a type-string from each data-item.
-- **topLevelMeta** (optional): An *object* or a *function* that describes the top-level meta. (If it is an object values can be string or function).
-- **topLevelLinks** (optional): An *object* or a *function* that describes the top-level links. (If it is an object values can be string or function).
+- **topLevelMeta** (optional): Describes the top-level meta. It can be:
+    - An *object* (values can be string or function).
+    - A *function* with one argument `function(extraData) { ... }` or with two arguments `function(data, extraData) { ... }`
+- **topLevelLinks** (optional): Describes the top-level links. It can be:
+    - An *object* (values can be string or function).
+    - A *function* with one argument `function(extraData) { ... }` or with two arguments `function(data, extraData) { ... }`
 
 Example :
 ```javascript

Diff for: lib/JSONAPISerializer.js

@@ -116,20 +116,20 @@ module.exports = class JSONAPISerializer {
    * @param {string|Object} 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} [extraOptions] additional data that can be used in topLevelMeta options.
+   * @param {Object} [extraData] additional data that can be used in topLevelMeta options.
    * @return {Object} serialized data.
    */
-  serialize(type, data, schema, extraOptions) {
+  serialize(type, data, schema, extraData) {
     // Support optional arguments (schema)
     if (arguments.length === 3) {
       if (_.isPlainObject(schema)) {
-        extraOptions = schema;
+        extraData = schema;
         schema = 'default';
       }
     }
 
     schema = schema || 'default';
-    extraOptions = extraOptions || {};
+    extraData = extraData || {};
 
     const included = [];
     let serializedData;
@@ -139,7 +139,7 @@ module.exports = class JSONAPISerializer {
       const typeOption = this.validateDynamicTypeOptions(type);
       // Override top level data
       topLevelOption = { topLevelMeta: typeOption.topLevelMeta, topLevelLinks: typeOption.topLevelLinks };
-      serializedData = this.serializeMixedData(typeOption, data, included);
+      serializedData = this.serializeMixedData(typeOption, data, included, extraData);
     } else { // Serialize data with the defined type
       if (!this.schemas[type]) {
         throw new Error(`No type registered for ${type}`);
@@ -151,16 +151,16 @@ module.exports = class JSONAPISerializer {
 
       const resourceOpts = this.schemas[type][schema];
       topLevelOption = { topLevelMeta: resourceOpts.topLevelMeta, topLevelLinks: resourceOpts.topLevelLinks };
-      serializedData = this.serializeData(type, data, resourceOpts, included);
+      serializedData = this.serializeData(type, data, resourceOpts, included, extraData);
     }
 
 
     return {
       jsonapi: {
         version: '1.0',
       },
-      meta: this.processOptionsValues(extraOptions, topLevelOption.topLevelMeta),
-      links: this.processOptionsValues(extraOptions, topLevelOption.topLevelLinks),
+      meta: this.processOptionsValues(data, extraData, topLevelOption.topLevelMeta, 'extraData'),
+      links: this.processOptionsValues(data, extraData, topLevelOption.topLevelLinks, 'extraData'),
       data: serializedData,
       included: this.serializeIncluded(included),
     };
@@ -175,20 +175,20 @@ module.exports = class JSONAPISerializer {
    * @param {string} type resource's type.
    * @param {Object|Object[]} data input data.
    * @param {string} [schema=default] resource's schema name.
-   * @param {Object} [extraOptions] additional data that can be used in topLevelMeta options.
+   * @param {Object} [extraData] additional data that can be used in topLevelMeta options.
    * @return {Promise} resolves with serialized data.
    */
-  serializeAsync(type, data, schema, extraOptions) {
+  serializeAsync(type, data, schema, extraData) {
     // Support optional arguments (schema)
     if (arguments.length === 3) {
       if (_.isPlainObject(schema)) {
-        extraOptions = schema;
+        extraData = schema;
         schema = 'default';
       }
     }
 
     schema = schema || 'default';
-    extraOptions = extraOptions || {};
+    extraData = extraData || {};
 
     const included = [];
     const isDataArray = Array.isArray(data);
@@ -223,8 +223,8 @@ module.exports = class JSONAPISerializer {
         try {
           // Serialize a single item of the data-array.
           const serializedItem = isDynamicType
-          ? this.serializeMixedData(type, item, included)
-          : this.serializeData(type, item, resourceOpts, included);
+          ? this.serializeMixedData(type, item, included, extraData)
+          : this.serializeData(type, item, resourceOpts, included, extraData);
 
           // If the serialized item is null, we won't push it to the stream,
           // as pushing a null-value causes streams to end.
@@ -252,8 +252,8 @@ module.exports = class JSONAPISerializer {
           jsonapi: {
             version: '1.0',
           },
-          meta: this.processOptionsValues(extraOptions, topLevelOption.topLevelMeta),
-          links: this.processOptionsValues(extraOptions, topLevelOption.topLevelLinks),
+          meta: this.processOptionsValues(extraData, data, topLevelOption.topLevelMeta),
+          links: this.processOptionsValues(extraData, data, topLevelOption.topLevelLinks),
           // If the source data was an array, we just pass the serialized data array.
           // Otherwise we try to take the first (and only) item of it or pass null.
           data: isDataArray ? serializedData : (serializedData[0] || null),
@@ -373,9 +373,10 @@ module.exports = class JSONAPISerializer {
    * @param {Object|Object[]} data input data.
    * @param {options} options resource's configuration options.
    * @param {Object[]} included.
+   * @param {Object} extraData additional data.
    * @return {Object|Object[]} serialized data.
    */
-  serializeData(type, data, options, included) {
+  serializeData(type, data, options, included, extraData) {
     // Empty data
     if (_.isEmpty(data)) {
       // Return [] or null
@@ -384,16 +385,16 @@ module.exports = class JSONAPISerializer {
 
     // Array data
     if (Array.isArray(data)) {
-      return data.map(d => this.serializeData(type, d, options, included));
+      return data.map(d => this.serializeData(type, d, options, included, extraData));
     }
 
     // Single data
     return {
       type,
       id: data[options.id].toString(),
       attributes: this.serializeAttributes(data, options),
-      relationships: this.serializeRelationships(data, options, included),
-      links: this.processOptionsValues(data, options.links),
+      relationships: this.serializeRelationships(data, options, included, extraData),
+      links: this.processOptionsValues(data, extraData, options.links),
     };
   }
 
@@ -406,9 +407,10 @@ module.exports = class JSONAPISerializer {
    * @param {Object} typeOption a dynamic type options.
    * @param {Object|Object[]} data input data.
    * @param {Object[]} included.
+   * @param {Object} extraData additional data.
    * @return {Object|Object[]} serialized data.
    */
-  serializeMixedData(typeOption, data, included) {
+  serializeMixedData(typeOption, data, included, extraData) {
     // Empty data
     if (_.isEmpty(data)) {
       // Return [] or null
@@ -417,7 +419,7 @@ module.exports = class JSONAPISerializer {
 
     // Array data
     if (Array.isArray(data)) {
-      return data.map(d => this.serializeMixedData(typeOption, d, included));
+      return data.map(d => this.serializeMixedData(typeOption, d, included, extraData));
     }
 
     // Single data
@@ -434,7 +436,7 @@ module.exports = class JSONAPISerializer {
       throw new Error(`No type registered for ${type}`);
     }
 
-    return this.serializeData(type, data, this.schemas[type].default, included);
+    return this.serializeData(type, data, this.schemas[type].default, included, extraData);
   }
 
   /**
@@ -519,9 +521,10 @@ module.exports = class JSONAPISerializer {
    * @param {Object|Object[]} data input data.
    * @param {Object} options resource's configuration options.
    * @param {Object[]} included.
+   * @param {Object} extraData additional data.
    * @return {Object} serialized relationships.
    */
-  serializeRelationships(data, options, included) {
+  serializeRelationships(data, options, included, extraData) {
     const serializedRelationships = {};
 
     Object.keys(options.relationships).forEach((relationship) => {
@@ -543,8 +546,8 @@ module.exports = class JSONAPISerializer {
       }
 
       const serializeRelationship = {
-        links: this.processOptionsValues(data, rOptions.links),
-        data: this.serializeRelationship(rOptions.type, data[relationshipKey], this.schemas[rOptions.type][schema], included),
+        links: this.processOptionsValues(data, extraData, rOptions.links),
+        data: this.serializeRelationship(rOptions.type, data[relationshipKey], this.schemas[rOptions.type][schema], included, extraData),
       };
 
       relationship = (options.convertCase) ? this._convertCase(relationship, options.convertCase) : relationship;
@@ -565,9 +568,10 @@ module.exports = class JSONAPISerializer {
    * @param {Object|Object[]} rData relationship's data.
    * @param {Object} rOptions relationship's configuration options.
    * @param {Object[]} included.
+   * @param {Object} extraData additional data.
    * @return {Object|Object[]} serialized relationship data.
    */
-  serializeRelationship(rType, rData, rOptions, included) {
+  serializeRelationship(rType, rData, rOptions, included, extraData) {
     // No relationship data
     if (rData === undefined) {
       return undefined;
@@ -581,7 +585,7 @@ module.exports = class JSONAPISerializer {
 
     // To-many relationships
     if (Array.isArray(rData)) {
-      return rData.map(d => this.serializeRelationship(rType, d, rOptions, included));
+      return rData.map(d => this.serializeRelationship(rType, d, rOptions, included, extraData));
     }
 
     // To-one relationship
@@ -598,28 +602,38 @@ module.exports = class JSONAPISerializer {
     } else {
         // Relationship has been populated
       serializedRelationship.id = rData[rOptions.id].toString();
-      included.push(this.serializeData(rType, rData, rOptions, included));
+      included.push(this.serializeData(rType, rData, rOptions, included, extraData));
     }
     return serializedRelationship;
   }
 
   /**
    * Process options values.
-   * Allows options to be an object or a function.
+   * Allows options to be an object or a function with 1 or 2 arguments
    *
    * @method JSONAPISerializer#processOptionsValues
    * @private
    * @param {Object} data data passed to functions options
+   * @param {Object} extraData additional data passed to functions options
    * @param {Object} options configuration options.
+   * @param {string} fallbackModeIfOneArg fallback mode if only one argument is passed to function.
+   * Avoid breaking changes with issue https://github.com/danivek/json-api-serializer/issues/27.
    * @return {Object}
    */
-  processOptionsValues(data, options) {
+  processOptionsValues(data, extraData, options, fallbackModeIfOneArg) {
     let processedOptions = {};
     if (options && typeof options === 'function') {
-      processedOptions = options(data);
+      // Backward compatible with functions with one 'extraData' argument
+      processedOptions = (fallbackModeIfOneArg === 'extraData' && options.length === 1) ? options(extraData) : options(data, extraData);
     } else {
       Object.keys(options).forEach((key) => {
-        const processedValue = options[key] && typeof options[key] === 'function' ? options[key](data) : options[key];
+        let processedValue = {};
+        if (options[key] && typeof options[key] === 'function') {
+          // Backward compatible with functions with one 'extraData' argument
+          processedValue = (fallbackModeIfOneArg === 'extraData' && options[key].length === 1) ? options[key](extraData) : options[key](data, extraData);
+        } else {
+          processedValue = options[key];
+        }
         Object.assign(processedOptions, { [key]: processedValue });
       });
     }