Support transforming column values in the Mapper

Author: jorgebay

doc/features/mapper/defining-mappings/README.md

@@ -64,7 +64,7 @@ To use multiple tables/views with the same model, specify the names in the `Mapp
 ```javascript
 const mappingOptions = {
   models: {
-    'User': {
+    'Video': {
       tables: [ 'videos', 'user_videos', 'latest_videos' ],
       mappings: new UnderscoreCqlToCamelCaseMappings(),
       columns: {
@@ -90,6 +90,38 @@ When selecting rows, the most suitable table will be used according to the table
 const result = await videoMapper.find({ userId });
 ```
 
+## Using custom type conversions
+
+When representing your model properties in a way that requires transformation from and to the column values, you can
+define `fromModel` and `toModel` functions to perform the conversions.
+
+For example, consider a `text` column that contains a JSON string and you want to represent it as an JavaScript
+`Object`.
+
+```javascript
+const mappingOptions = {
+  models: {
+    'User': {
+      tables: ['users'],
+      mappings: new UnderscoreCqlToCamelCaseMappings(),
+      columns: {
+        'userid': 'userId',
+        'info': {
+          name: 'user_info',
+          fromModel: JSON.stringify,
+          toModel: JSON.parse
+        }
+      }
+    }
+  }
+};
+```
+
+Now, you can interact with the model property as an `Object` rather than as a `String`.
+
+```javascript
+await userMapper.insert({ userId, info: { birthdate, favoriteBrowser } });
+```
 
 ## Mapping to a Materialized View
 

doc/features/mapper/getting-started/README.md

@@ -10,8 +10,8 @@ const Mapper = cassandra.mapping.Mapper;
 const client = new Client({ contactPoints, localDataCenter, keyspace });
 ```
 
-Create a `Mapper` instance and reuse it across your application. You can specify you model properties and how those
-are mapped to table columns can be defined in the [MappingOptions](../defining-mappings/). 
+Create a `Mapper` instance and reuse it across your application. You can define how your model properties are mapped
+to table columns in the [MappingOptions](../defining-mappings/). 
 
 ```javascript
 const mapper = new Mapper(client, { 

lib/mapping/doc-info-adapter.js

@@ -41,7 +41,10 @@ class DocInfoAdapter {
     }
 
     return propertyKeys.map(propertyName => ({
-      propertyName, columnName: mappingInfo.getColumnName(propertyName), value: doc[propertyName]
+      propertyName,
+      columnName: mappingInfo.getColumnName(propertyName),
+      value: doc[propertyName],
+      fromModel: mappingInfo.getFromModelFn(propertyName)
     }));
   }
 

lib/mapping/index.d.ts

@@ -112,10 +112,16 @@ export namespace mapping {
   type ModelOptions = {
     tables?: string[] | ModelTables[];
     mappings?: TableMappings;
-    columns?: { [key: string]: string };
+    columns?: { [key: string]: string|ModelColumnOptions };
     keyspace?: string;
   }
 
+  type ModelColumnOptions = {
+    name: string;
+    toModel?: (columnValue: any) => any;
+    fromModel?: (modelValue: any) => any;
+  };
+
   interface ModelBatchItem {
 
   }

lib/mapping/mapping-handler.js

@@ -134,7 +134,7 @@ class MappingHandler {
   _executeSelect(query, paramsGetter, doc, docInfo, executionOptions, cacheItem) {
     const options = DocInfoAdapter.adaptAllOptions(executionOptions, true);
 
-    return this._client.execute(query, paramsGetter(doc, docInfo), options)
+    return this._client.execute(query, paramsGetter(doc, docInfo, this.info), options)
       .then(rs => {
         if (cacheItem.resultAdapter === null) {
           cacheItem.resultAdapter = ResultMapper.getSelectAdapter(this.info, rs);
@@ -368,7 +368,7 @@ class MappingHandler {
     cacheItem.executor = function singleExecutor(doc, docInfo, executionOptions) {
       const options = DocInfoAdapter.adaptOptions(executionOptions, queryInfo.isIdempotent);
 
-      return self._client.execute(queryInfo.query, queryInfo.paramsGetter(doc, docInfo), options)
+      return self._client.execute(queryInfo.query, queryInfo.paramsGetter(doc, docInfo, self.info), options)
         .then(rs => new Result(rs, self.info, ResultMapper.getMutationAdapter(rs)));
     };
 
@@ -385,7 +385,7 @@ class MappingHandler {
       // Use the params getter function to obtain the parameters each time
       const queryAndParams = queries.map(q => ({
         query: q.query,
-        params: q.paramsGetter(doc, docInfo)
+        params: q.paramsGetter(doc, docInfo, self.info)
       }));
 
       const options = DocInfoAdapter.adaptOptions(executionOptions, isIdempotent);

lib/mapping/model-mapping-info.js

@@ -29,37 +29,52 @@ class ModelMappingInfo {
    * @param {String} keyspace
    * @param {Array<{name, isView}>} tables
    * @param {TableMappings} mappings
-   * @param {Map<String,String>} columns
+   * @param {Map<String,ModelColumnInfo>} columns
    */
   constructor(keyspace, tables, mappings, columns) {
     this.keyspace = keyspace;
     this.tables = tables;
     this._mappings = mappings;
     this._columns = columns;
+
+    // Define a map of column information per property name
+    /** @type {Map<String, ModelColumnInfo>} */
     this._documentProperties = new Map();
-    columns.forEach((propName, columnName) => this._documentProperties.set(propName, columnName));
+    for (const modelColumnInfo of columns.values()) {
+      this._documentProperties.set(modelColumnInfo.propertyName, modelColumnInfo);
+    }
   }
 
   getColumnName(propName) {
-    const columnName = this._documentProperties.get(propName);
-    if (columnName !== undefined) {
+    const modelColumnInfo = this._documentProperties.get(propName);
+    if (modelColumnInfo !== undefined) {
       // There is an specific name transformation between the column name and the property name
-      return columnName;
+      return modelColumnInfo.columnName;
     }
     // Rely on the TableMappings (i.e. maybe there is a convention defined for this property)
     return this._mappings.getColumnName(propName);
   }
 
   getPropertyName(columnName) {
-    const propName = this._columns.get(columnName);
-    if (propName !== undefined) {
+    const modelColumnInfo = this._columns.get(columnName);
+    if (modelColumnInfo !== undefined) {
       // There is an specific name transformation between the column name and the property name
-      return propName;
+      return modelColumnInfo.propertyName;
     }
     // Rely on the TableMappings (i.e. maybe there is a convention defined for this column)
     return this._mappings.getPropertyName(columnName);
   }
 
+  getFromModelFn(propName) {
+    const modelColumnInfo = this._documentProperties.get(propName);
+    return modelColumnInfo !== undefined ? modelColumnInfo.fromModel : null;
+  }
+
+  getToModelFn(columnName) {
+    const modelColumnInfo = this._columns.get(columnName);
+    return modelColumnInfo !== undefined ? modelColumnInfo.toModel : null;
+  }
+
   newInstance() {
     return this._mappings.newObjectInstance();
   }
@@ -123,7 +138,7 @@ class ModelMappingInfo {
     const columns = new Map();
     if (modelOptions.columns !== null && typeof modelOptions.columns === 'object') {
       Object.keys(modelOptions.columns).forEach(columnName => {
-        columns.set(columnName, modelOptions.columns[columnName]);
+        columns.set(columnName, ModelColumnInfo.parse(columnName, modelOptions.columns[columnName]));
       });
     }
 
@@ -144,4 +159,36 @@ class ModelMappingInfo {
   }
 }
 
+class ModelColumnInfo {
+  constructor(columnName, propertyName, toModel, fromModel) {
+    this.columnName = columnName;
+    this.propertyName = propertyName;
+
+    if (toModel && typeof toModel !== 'function') {
+      throw new TypeError(`toModel type for property '${propertyName}' should be a function (obtained ${
+        typeof toModel})`);
+    }
+
+    if (fromModel && typeof fromModel !== 'function') {
+      throw new TypeError(`fromModel type for property '${propertyName}' should be a function (obtained ${
+        typeof fromModel})`);
+    }
+
+    this.toModel = toModel;
+    this.fromModel = fromModel;
+  }
+
+  static parse(columnName, value) {
+    if (!value) {
+      return new ModelColumnInfo(columnName, columnName);
+    }
+
+    if (typeof value === 'string') {
+      return new ModelColumnInfo(columnName, value);
+    }
+
+    return new ModelColumnInfo(columnName, value.name || columnName, value.toModel, value.fromModel);
+  }
+}
+
 module.exports = ModelMappingInfo;

lib/mapping/q.js

@@ -28,8 +28,9 @@ class QueryOperator {
    * @param {String} key
    * @param value
    * @param [hasChildValues]
+   * @param [isInOperator]
    */
-  constructor(key, value, hasChildValues) {
+  constructor(key, value, hasChildValues, isInOperator) {
     /**
      * The CQL key representing the operator
      * @type {string}
@@ -45,6 +46,11 @@ class QueryOperator {
      * Determines whether a query operator can have child values or operators (AND, OR)
      */
     this.hasChildValues = hasChildValues;
+
+    /**
+     * Determines whether this instance represents CQL "IN" operator.
+     */
+    this.isInOperator = isInOperator;
   }
 }
 
@@ -95,7 +101,7 @@ const q = {
     if (!Array.isArray(arr)) {
       throw new errors.ArgumentError('IN operator supports only Array values');
     }
-    return new QueryOperator('IN', arr);
+    return new QueryOperator('IN', arr, false, true);
   },
 
   gt: function gt(value) {

lib/mapping/query-generator.js

@@ -63,7 +63,7 @@ class QueryGenerator {
   }
 
   static selectParamsGetter(propertiesInfo, limit) {
-    let scriptText = '(function getParametersSelect(doc, docInfo) {\n';
+    let scriptText = '(function getParametersSelect(doc, docInfo, mappingInfo) {\n';
     scriptText += '  return [';
 
     scriptText += QueryGenerator._valueGetterExpression(propertiesInfo);
@@ -78,8 +78,8 @@ class QueryGenerator {
     // Finish return statement
     scriptText += '];\n})';
 
-    const script = new vm.Script(scriptText);
-    return script.runInThisContext({ filename: vmFileName});
+    const script = new vm.Script(scriptText, { filename: vmFileName });
+    return script.runInThisContext();
   }
 
   /**
@@ -132,7 +132,7 @@ class QueryGenerator {
   }
 
   static _insertParamsGetter(propertiesInfo, docInfo) {
-    let scriptText = '(function getParametersInsert(doc, docInfo) {\n';
+    let scriptText = '(function getParametersInsert(doc, docInfo, mappingInfo) {\n';
     scriptText += '  return [';
 
     scriptText += QueryGenerator._valueGetterExpression(propertiesInfo);
@@ -144,8 +144,8 @@ class QueryGenerator {
     // Finish return statement
     scriptText += '];\n})';
 
-    const script = new vm.Script(scriptText);
-    return script.runInThisContext({ filename: vmFileName});
+    const script = new vm.Script(scriptText, { filename: vmFileName });
+    return script.runInThisContext();
   }
 
   /**
@@ -249,7 +249,7 @@ class QueryGenerator {
    * @returns {Function}
    */
   static _updateParamsGetter(primaryKeys, propertiesInfo, when, ttl) {
-    let scriptText = '(function getParametersUpdate(doc, docInfo) {\n';
+    let scriptText = '(function getParametersUpdate(doc, docInfo, mappingInfo) {\n';
     scriptText += '  return [';
 
     if (typeof ttl === 'number') {
@@ -271,8 +271,8 @@ class QueryGenerator {
     // Finish return statement
     scriptText += '];\n})';
 
-    const script = new vm.Script(scriptText);
-    return script.runInThisContext({ filename: vmFileName});
+    const script = new vm.Script(scriptText, { filename: vmFileName });
+    return script.runInThisContext();
   }
 
   /**
@@ -346,7 +346,7 @@ class QueryGenerator {
    * @returns {Function}
    */
   static _deleteParamsGetter(primaryKeys, propertiesInfo, when) {
-    let scriptText = '(function getParametersDelete(doc, docInfo) {\n';
+    let scriptText = '(function getParametersDelete(doc, docInfo, mappingInfo) {\n';
     scriptText += '  return [';
 
     // Where clause
@@ -360,8 +360,8 @@ class QueryGenerator {
     // Finish return statement
     scriptText += '];\n})';
 
-    const script = new vm.Script(scriptText);
-    return script.runInThisContext({ filename: vmFileName});
+    const script = new vm.Script(scriptText, { filename: vmFileName });
+    return script.runInThisContext();
   }
 
   /**
@@ -375,20 +375,29 @@ class QueryGenerator {
     objectName = objectName || 'doc';
 
     return propertiesInfo
-      .map(p => QueryGenerator._valueGetterSingle(`${objectName}['${p.propertyName}']`, p.value))
+      .map(p =>
+        QueryGenerator._valueGetterSingle(`${objectName}['${p.propertyName}']`, p.propertyName, p.value, p.fromModel))
       .join(', ');
   }
 
-  static _valueGetterSingle(prefix, value) {
+  static _valueGetterSingle(prefix, propName, value, fromModelFn) {
+    let valueGetter = prefix;
+
     if (value instanceof QueryOperator) {
       if (value.hasChildValues) {
-        return `${QueryGenerator._valueGetterSingle(`${prefix}.value[0]`, value.value[0])}` +
-          `, ${QueryGenerator._valueGetterSingle(`${prefix}.value[1]`, value.value[1])}`;
+        return `${QueryGenerator._valueGetterSingle(`${prefix}.value[0]`, propName, value.value[0], fromModelFn)}` +
+          `, ${QueryGenerator._valueGetterSingle(`${prefix}.value[1]`, propName, value.value[1], fromModelFn)}`;
+      }
+
+      valueGetter = `${prefix}.value`;
+
+      if (value.isInOperator && fromModelFn) {
+        // Transform each individual value
+        return `${valueGetter}.map(v => ${QueryGenerator._getMappingFunctionCall(propName, 'v')})`;
       }
-      return `${prefix}.value`;
     }
 
-    return prefix;
+    return !fromModelFn ? valueGetter : QueryGenerator._getMappingFunctionCall(propName, valueGetter);
   }
 
   /**
@@ -402,7 +411,13 @@ class QueryGenerator {
     prefix = prefix || 'doc';
 
     return propertiesInfo
-      .map(p => `${prefix}['${p.propertyName}']${p.value instanceof QueryAssignment ? '.value' : ''}`)
+      .map(p => {
+        const valueGetter = `${prefix}['${p.propertyName}']${p.value instanceof QueryAssignment ? '.value' : ''}`;
+        if (p.fromModel) {
+          return QueryGenerator._getMappingFunctionCall(p.propertyName, valueGetter);
+        }
+        return valueGetter;
+      })
       .join(', ');
   }
 
@@ -412,6 +427,10 @@ class QueryGenerator {
       .join(' AND ');
   }
 
+  static _getMappingFunctionCall(propName, valueGetter) {
+    return `mappingInfo.getFromModelFn('${propName}')(${valueGetter})`;
+  }
+
   static _getSingleCondition(columnName, value) {
     if (value instanceof QueryOperator) {
       if (value.hasChildValues) {