map-transform 0.3.11 → 0.4.0-alpha.3

package/README.md

@@ -85,8 +85,8 @@ const def2 = [
   {
     title: 'name',
     author: 'meta.author',
-    date: 'meta.date'
-  }
+    date: 'meta.date',
+  },
 ]
 
 const target2 = mapTransform(def2)(source)
@@ -105,15 +105,15 @@ const { mapTransform, transform } = require('map-transform')
 // ....
 
 // Write a transform function, that accepts a value and returns a value
-const msToDate = ms => new Date(ms).toISOString()
+const msToDate = (ms) => new Date(ms).toISOString()
 
 const def3 = [
   'data[0].content',
   {
     title: 'name',
     author: 'meta.author',
-    date: ['meta.date', transform(msToDate)]
-  }
+    date: ['meta.date', transform(msToDate)],
+  },
 ]
 
 const target3 = mapTransform(def3)(source)
@@ -143,6 +143,14 @@ Install from npm:
 npm install map-transform --save
 ```
 
+## Breaking changes in v0.4
+
+- Map objects won't be mapped over an array by default. You have to specify
+  `$iterate: true`
+- The `alt` operation now accepts any type of pipeline, but not a helper
+  function
+- The root path prefix is changed from `$` to `^`
+
 ## Usage
 
 ### The transform object
@@ -159,15 +167,15 @@ taste.
 
 ```javascript
 const def1 = {
-  'data.entry.title': 'heading'
+  'data.entry.title': 'heading',
 }
 
 const def2 = {
   data: {
     entry: {
-      title: 'heading'
-    }
-  }
+      title: 'heading',
+    },
+  },
 }
 
 // def1 and def2 are identical, and will result in an object like this:
@@ -180,28 +188,55 @@ const def2 = {
 // }
 ```
 
-If MapTransform happens upon an array in the source data, it will map it and
-set an array where each item is mapped according to the mapping object. But to
-ensure that you get an array, even when the source data contains only an object,
-you may suffix a key with brackets `[]`.
+When you transform an array of data with a mapping object, each item in the
+data array will be be transformed with the mapping object.
 
 ```javascript
 const def3 = {
-  'data.entries[]': {
+  title: 'heading',
+}
+
+// -->
+// [
+//   { title: 'The first heading' },
+//   { title: 'The second heading' }
+// ]
+```
+
+If you want to apply the mapping object to the entire array – not each item in
+the array – set `$iterate: false` on the mapping object or wrap the object in a
+transform pipeline.
+
+**Note:** When a mapping object is part of a transform pipeline, the default is
+to not iterate. See [**transform pipeline**](#transform-pipeline) for more.
+
+A key will set whatever is returned by the pipeline (see
+[next section](#values-on-the-transform-object)), whether it is a string, a
+boolean, an array, etc. If you want to ensure that you always get an array, you
+can suffix the key with `[]`. Any value that is not an array will be wrapped in
+one.
+
+```javascript
+const def27 = {
+  $iterate: false
+  'articles[]': {
     title: 'heading'
   }
 }
 
-// def3 will always give you entries as an array:
+// -->
 // {
-//   data: {
-//     entries: [
-//       {title: 'The actual heading'}
-//     ]
-//   }
+//   articles: [
+//     { title: 'Wrapped in an array, even if the data was just an object' },
+//   ]
 // }
 ```
 
+A bonus of using the `[]` suffix, is that when key has another transform object
+as its value, this transform object will be iterated by default (no need to set
+the `$iterate` property). This does not happen to pipelines, paths, or
+operations.
+
 #### Values on the transform object
 
 The values on the transform objects define how to retrieve and transform data
@@ -217,7 +252,7 @@ is at this path on the source object.
 
 ```javascript
 const def4 = {
-  title: 'data.item.heading'
+  title: 'data.item.heading',
 }
 
 const source1 = {
@@ -225,9 +260,9 @@ const source1 = {
     item: {
       id: 'item1',
       heading: 'The actual heading',
-      intro: 'The actual intro'
-    }
-  }
+      intro: 'The actual intro',
+    },
+  },
 }
 
 // `mapTransform(def4)(source1)` will transform to:
@@ -251,7 +286,7 @@ an array by indicating the array index in the brackets.
 
 ```javascript
 const def5 = {
-  title: 'data.items[0].heading'
+  title: 'data.items[0].heading',
 }
 
 // def5 will pull the heading from the first item in the `items` array, and will
@@ -267,6 +302,30 @@ the transform pipeline (which the dot notation path really is, and – come to
 think of it – the transform object itself too). This is explained in detail
 below.
 
+#### A note on undefined and null
+
+MapTransform will treat `undefined` as a value that is not set, and so a
+transform object will not be applied to it. So if an `undefined` value meets
+a transform object, it will produce `undefined`, regardsless of the shape of the
+transform object.
+
+This is not the case for `null`, though. MapTransform treats `null` as a value,
+an intended nothing, and will apply a transform object to it, even though it
+will most likely produce nothing but default values. To change this behavior,
+set `mutateNull: false` on the `options` object passed to MapTransform. This
+will essentially make MapTransform treat `null` the same way as `undefined` when
+it comes to the transform object.
+
+#### Directional transform objects
+
+A transform object is by default applied on forward transformations and in
+reverse. You may alter this by setting the `$direction` prop on a transform
+object, with `fwd`, `rev`, or `both` (the default) as possible values.
+
+When running a forward transformation, transform objects marked with
+`$direction: 'rev'` will be skipped. The same goes for `$direction: 'fwd'` in
+reverse.
+
 ### Transform pipeline
 
 The idea of the transform pipeline, is that you describe a set of
@@ -277,7 +336,7 @@ original format again (although with a potential loss of data, if not all
 properties are transformed). This is what you do in a
 [reverse mapping](#reverse-mapping).
 
-One way to put it is that the pipeline describes the difference between the two
+One way to put it, is that the pipeline describes the difference between the two
 possible states of the data, and allows you to go back and forth between them.
 Or you can just view it as operations applied in the order they are defined – or
 back again.
@@ -299,24 +358,33 @@ import { transform, filter } from 'map-transform'
 const def6 = [
   'data.items[]',
   {
+    $iterate: true,
     id: 'articleNo',
     title: ['headline', transform(maxLength(20))],
-    sections: 'meta.sections[].id'
+    sections: 'meta.sections[].id',
   },
-  filter(onlyItemsWithSection)
+  filter(onlyItemsWithSection),
 ]
 ```
 
 (Note that in this example, both `maxLength` and `onlyItemsWithSection` are
 custom functions for this case, but their implementations are not provided.)
 
-#### `transform(fn, fnRev)` operation
+**A note on arrays:** In a transform pipeline, the default behavior is to treat
+an array as any other data. The array will be passed on to a `transform()`
+operation, the entire array will be set on a path, etc. This also means that a
+mapping object will be applied to the entire array if nothing else is specified.
+In the example above, we have set `$iterate: true` on the mapping object, to
+signal that we want the mapping to be applied to the items of any array. See
+also [the `iterate` operation](#iteratepipeline-operation) for more.
+
+#### `transform(transformFn, transformFnRev)` operation
 
 The simple beauty of the `transform()` operation, is that it will apply whatever
 function you provide it with to the data at that point in the pipeline. It's
 completely up to you to write the function that does the transformation.
 
-You may supply a second function (`fnRev`), that will be used when
+You may supply a second function (`transformFnRev`), that will be used when
 [reverse mapping](#reverse-mapping). If you only supplies one function, it will
 be used in both directions. You may supply `null` for either of these, to make
 it uni-directional, but it might be clearer to use `fwd()` or `rev()` operations
@@ -336,16 +404,16 @@ on an object. You would probably just not get the end result you expected.
 ```javascript
 import { mapTransform, transform } from 'map-transform'
 
-const ensureInteger = data => Number.parseInt(data, 10) || 0
+const ensureInteger = (data) => Number.parseInt(data, 10) || 0
 const def7 = {
-  count: ['statistics.views', transform(ensureInteger)]
+  count: ['statistics.views', transform(ensureInteger)],
 }
 
 const data = {
   statistics: {
-    view: '18'
+    view: '18',
     // ...
-  }
+  },
 }
 
 mapTransform(def7)(data)
@@ -381,41 +449,50 @@ Example transformation pipeline with a `yearsSince` function:
 
 ```javascript
 const def8 = {
-  age: ['birthyear', yearsSince(new Date())]
+  age: ['birthyear', yearsSince(new Date())],
 }
 ```
 
+**Note:** When the `transform` operation is applied to an array, it will not
+iterate the array. Mapping over each item needs to be handled in the transform
+itself, or wrap the `transform` operation in an `iterate` operation.
+
 You may also define a transform operation as an object:
 
 ```javascript
 import { mapTransform } from 'map-transform'
 
-const ensureInteger = operands => data => Number.parseInt(data, 10) || 0
-const customFunctions = { ensureInteger }
+const ensureInteger = (operands) => (data) => Number.parseInt(data, 10) || 0
+const functions = { ensureInteger }
 const def7asObject = {
-  count: ['statistics.views', { $transform: 'ensureInteger' }]
+  count: ['statistics.views', { $transform: 'ensureInteger' }],
 }
 
 const data = {
   statistics: {
-    view: '18'
+    view: '18',
     // ...
-  }
+  },
 }
 
-mapTransform(def7asObject, { customFunctions })(data)
+mapTransform(def7asObject, { functions })(data)
 // --> {
 //   count: 18
 // }
 ```
 
-Note that the function itself is passed on the `customFunctions` object. When
+Note that the function itself is passed on the `functions` object. When
 you provide the custom function this way, it should be given as a function
 accepting an object with operands / arguments, that returns the actual function
 used in the transform. Any properties given on the operation object, apart from
 `$transform`, will be passed in the `operands` object.
 
-#### `filter(fn)` operation
+When you define the `transform` operation as an object, you may specify
+`$iterate: true` on the object to apply the transform to every item on an array,
+if an array is encountered. You may also set `$direction: 'fwd'` or
+`$direction: 'rev'` to have it transform in one direction only.
+
+#### `filter(conditionFn)` operation
 
 Just like the transform operation, the filter operation will apply whatever
 function you give it to the data at that point in the transform pipeline, but
@@ -458,7 +535,7 @@ Defining a filter operation as an object:
 import { mapTransform } from 'map-transform'
 
 const onlyActives = (data) => data.active
-const customFunctions = { onlyActives }
+const functions = { onlyActives }
 const def9asObject = [
   'members'
   {
@@ -469,7 +546,120 @@ const def9asObject = [
 ]
 ```
 
-See the `transform()` operation on how defining as an object works.
+You may also set `$direction: 'fwd'` or `$direction: 'rev'` on the object, to
+have it filter in one direction only.
+
+See the `transform()` operation for more on how defining as an object works.
+
+#### `ifelse(conditionFn, truePipeline, falsePipeline)` operation
+
+The `ifelse()` operation will run the `truePipeline` if the `conditionFn` results
+in `true`, otherwise it will run the `falsePipeline`. See
+[the `filter()` operation](#filterconditionFn-operation) for more on the
+requirements for the `conditionFn`.
+
+Both `truePipeline` and `falsePipeline` are optional, in case you only need to
+apply a pipeline in one of the cases.
+
+Example:
+
+```javascript
+import { mapTransform, ifelse } from 'map-transform'
+
+const onlyActives = (data) => data.active
+const def31 = [
+  'members'
+  {
+    name: 'name',
+    active: 'hasPayed'
+  },
+  ifelse(onlyActives, set('active[]'), set('inactive[]'))
+]
+```
+
+#### `iterate(pipeline)` operation
+
+If you want something to be mapped over the items of an array, the `iterate`
+operation is your friend. When you wrap another operation, a pipeline, or a
+mapping object in an `iterate` operation, it will be applied to each item.
+
+When iterating, the state's `context` will iterate as well, to support `alt`
+operations etc. that need to access the corresponding item in the context.
+
+In this example, each value in the array returned by `statistics[].views` will
+be transformed with the `ensureInteger` function, even if the function does not
+support arrays:
+
+```javascript
+import { mapTransform, iterate } from 'map-transform'
+
+const ensureInteger = data => Number.parseInt(data, 10) || 0
+const def26 = [
+  counts: ['statistics[].views', iterate(transform(ensureInteger))]
+]
+```
+
+The `iterate` operation may also be used to wrap mapping objects in a transform
+pipeline, however, setting `$iterate: true` on the object may be more
+convenient.
+
+#### `apply(pipelineId)` operation
+
+The apply operation allows pipelines to be reused. Several pipelines may be
+provided on the `pipelines` object on the `options` provided to
+`mapTransform()`, and the keys of the `pipelines` object serves as ids.
+When an id is passed to the apply operation as `pipelinedId`, the pipeline will
+be applied in the place of the apply operation and executed as if it was part of
+the pipeline definition in the first place.
+
+```javascript
+import { mapTransform, apply, transform } from 'map-transform'
+
+const ensureInteger = (data) => Number.parseInt(data, 10) || 0
+const pipelines = {
+  castEntry: {
+    title: ['title', transform(String)],
+    count: ['count', transform(ensureInteger)],
+  },
+}
+const def25 = [
+  {
+    title: 'heading',
+    count: 'statistics.views',
+  },
+  apply('castEntry'),
+]
+
+const data = {
+  heading: 'Entry 1',
+  statistics: {
+    view: '18',
+  },
+}
+
+mapTransform(def7)(data)
+// --> {
+//   title: 'Entry 1',
+//   count: 18
+// }
+```
+
+You may also define the apply operation as an operation object:
+
+```javascript
+const def25 = [
+  {
+    title: 'heading',
+    count: 'statistics.views',
+  },
+  { $apply: 'castEntry' },
+]
+```
+
+When you define the `apply` operation as an object, you may specify
+`$iterate: true` on the object to apply the pipeline to every item on an array,
+if an array is encountered. You may also set `$direction: 'fwd'` or
+`$direction: 'rev'` to have it apply in one direction only.
 
 #### `value(data)` operation
 
@@ -490,12 +680,23 @@ import { value, alt } from 'map-transform'
 const def10 = {
   id: 'data.customerNo',
   type: value('customer'),
-  name: ['data.name', alt(value('Anonymous'))]
+  name: ['data.name', alt(value('Anonymous'))],
 }
 ```
 
 The operation will not set anything when mapping with `.onlyMappedValues()`.
 
+If you want to define the `value` operation as an operation object, use
+`$transform` or `$alt`:
+
+```javascript
+const def10asObject = {
+  id: 'data.customerNo',
+  type: { $transform: 'value', value: 'customer' },
+  name: ['data.name', { $alt: 'value', value: 'Anonymous' }],
+}
+```
+
 #### `fixed(data)` operation
 
 The data given to the fixed operation, will be inserted in the pipeline in place
@@ -507,15 +708,20 @@ will be included when mapping with `.onlyMappedValues()` as well.
 
 #### `alt(pipeline)` operation
 
-The alt operation will apply the function or pipeline it is given when the data
-already in the pipeline is `undefined`. This is how you provide default values
-in MapTransform. The pipeline may be as simple as a `value()` operation, a dot
+The alt operation will apply the pipeline it is given when the data already in
+the pipeline is `undefined`. This is how you provide default values in
+MapTransform. The pipeline may be as simple as a `value()` operation, a dot
 notation path into the source data, or a full pipeline of several operations.
 
+When given an array, the `alt` operation will treat it as a value and do
+nothing, as it is not an `undefined` value. To provide the `alt` operation to
+every item in the array, please use the `iterate` operation.
+
 ```javascript
-import { alt, transform, value } from 'map-transform'
-const currentDate = data => new Date()
-const formatDate = data => {
+import { alt, transform, functions } from 'map-transform'
+const { value } = functions
+const currentDate = (data) => new Date()
+const formatDate = (data) => {
   /* implementation not included */
 }
 
@@ -526,30 +732,38 @@ const def11 = {
     'data.updateDate',
     alt('data.createDate'),
     alt(transform(currentDate)),
-    transform(formatDate)
-  ]
+    transform(formatDate),
+  ],
 }
 ```
 
 In the example above, we first try to set the `updatedAt` prop to the data found
 at `data.updateDate` in the source data. If that does not exist (i.e. we get
 `undefined`), the alt operation kicks in and try the path `data.createDate`. If
-we still have `undefined`, the second alt will call a transform operation with
-the `currentDate` function, that simply returns the current date as a JS object.
-Finally, another transform operation pipes whatever data we get from all of this
-through the `formatDate` function.
+we still have `undefined`, the second alt will call the customer function
+`currentDate`, that simply returns the current date as a JS object. Finally,
+another transform operation pipes whatever data we get from all of this through
+the `formatDate` function.
 
 You may also define an alt operation as an object:
 
 ```javascript
 const def11asObject = {
   id: 'data.id',
-  name: ['data.name', { $transform: 'alt', value: 'Anonymous' }]
+  name: ['data.name', { $alt: 'value', value: 'Anonymous' }],
+  updatedAt: [
+    'data.updateDate',
+    { $alt: 'get', path: 'data.createDate' },
+    { $alt: 'currentDate' },
+    { $transform: 'formatDate' },
+  ],
 }
 ```
 
-For now, only the value operand is supported. In the example above, the value
-`'Anonymous'` will be used when `data.name` is undefined.
+When you define the `alt` operation as an object, you may specify
+`$iterate: true` on the object to provide a default value to every `undefined`
+item on an array, if an array is encountered. You may also set
+`$direction: 'fwd'` or `$direction: 'rev'` to limit it to one direction only.
 
 #### `concat(pipeline, pipeline, ...)` operation
 
@@ -561,6 +775,49 @@ This operation will always return an array, even when it is given only one
 pipeline that does not return an array. Pipelines that does not result in a
 value (i.e. return `undefined`) will be filtered away.
 
+#### `merge(pipeline, pipeline, ...)` operation
+
+`merge()` will run all given pipelines and deep merge their results. Conflicts
+are resolved by prioritizing results from the rightmost of the conflicting
+pipelines.
+
+#### `modify(pipeline)` operation
+
+Use the `modify()` operation when you want the pipeline to modify an object,
+instead of replacing it.
+
+Example:
+
+```javascript
+import { modify } from 'map-transform'
+
+const def34 = modify({
+  data: 'data.deeply.placed.items',
+})
+```
+
+`def34` will in effect set the values placed at a deep path on the `data`
+prop. Giving this an object like:
+
+```javascript
+const response = {
+  status: 'ok',
+  data: { deeply: { placed: { items: [{ id: 'ent1' }] } } },
+}
+```
+
+...will result in:
+
+```javascript
+const response = {
+  status: 'ok',
+  data: [{ id: 'ent1' }],
+}
+```
+
+Had we ran this without the `modify()` operation, the returned object would only
+have the `data` prop.
+
 #### `fwd(pipeline)` and `rev(pipeline)` operation
 
 All operations in MapTransform will apply in both directions, although some of
@@ -573,11 +830,11 @@ pipeline when we're mapping in reverse.
 
 ```javascript
 import { fwd, rev, transform } from 'map-transform'
-const increment = data => data + 1
-const decrement = data => data - 1
+const increment = (data) => data + 1
+const decrement = (data) => data - 1
 
 const def12 = {
-  order: ['index', fwd(transform(increment)), rev(transform(decrement))]
+  order: ['index', fwd(transform(increment)), rev(transform(decrement))],
 }
 ```
 
@@ -630,7 +887,7 @@ This example results in the exact same pipeline as the example above:
 
 ```javascript
 const def14 = {
-  'content[]': 'data.items[].content'
+  'content[]': 'data.items[].content',
 }
 ```
 
@@ -659,13 +916,13 @@ const def15 = [
   {
     id: 'id',
     title: 'headline',
-    section: root('meta.section')
-  }
+    section: root('meta.section'),
+  },
 ]
 
 const data = {
   articles: [{ id: '1', headline: 'An article' } /* ... */],
-  meta: { section: 'news' }
+  meta: { section: 'news' },
 }
 
 mapTransform(def15)(data)
@@ -680,14 +937,14 @@ As you see, every item in the `articles[]` array, will be mapped with the
 items without the root operation.
 
 There's also a shortcut notation for root, by prefixing a dot notation path with
-`$`. This only works when the path is used for getting a value, and it will be
+`^`. This only works when the path is used for getting a value, and it will be
 plugged when used as set (i.e., it will return no value). This may be used in
 `get()` and `set()` operations, and in transformation objects.
 
 In the following example, `def16` and `def17` is exactly the same:
 
 ```javascript
-const def16 = get('$meta.section')
+const def16 = get('^meta.section')
 const def17 = divide(root('meta.section'), plug())
 ```
 
@@ -727,8 +984,8 @@ const data = {
   users: [
     { id: 'user1', name: 'User 1' },
     { id: 'user2', name: 'User 2' },
-    { id: 'user3', name: 'User 3' }
-  ]
+    { id: 'user3', name: 'User 3' },
+  ],
 }
 const mapper = mapTransform(def18)
 const mappedData = mapper(data)
@@ -741,31 +998,193 @@ mapper.rev(mappedData)
 // --> { content: { meta: { authors: ['user1', 'user3'] } } }
 ```
 
-#### `compare(path, value)` helper
+#### `compare({ path, operator, match, matchPath })` function
+
+This is a helper function intended for use with the `filter()` operation. You
+pass a dot notation `path` and a `match` value (string, number, boolean) to
+`compare()`, and it returns a function that you can pass to `filter()` for
+filtering away data that does not not have the value set at the provided path.
+
+As an alternative to `match`, you may specify a `matchPath`, which is a dot
+notation path, in which case the match value will be fetched from the provided
+data.
 
-This is a helper intended for use with the `filter()` operation. You pass a dot
-notation path and a value (string, number, boolean) to `compare()`, and it
-returns a function that you can pass to `filter()` for filtering away data that
-does not not have the value set at the provided path. If the path points to an
-array, the value is expected to be one of the values in the array.
+The default is to compare the values resulting from `path` and `match` or
+`matchPath` with equality, but other operations may be set on the `operator`
+property. Alternatives: `'='`, `'!='`, `'>'`, `'>='`, `'<'`, or `'<='`.
+
+If the path points to an array, the value is expected to be one of the values in
+the array.
 
 Here's an example where only data where role is set to 'admin' will be kept:
 
 ```javascript
-import { filter, compare } from 'map-transform'
+import { filter, functions } from 'map-transform'
+const { compare } = functions
 
 const def19 = [
   {
     name: 'name',
-    role: 'editor'
+    role: 'editor',
+  },
+  filter(compare({ path: 'role', operator: '=', match: 'admin' })),
+]
+```
+
+You may also define this with a transform object:
+
+```javascript
+const def19o = [
+  {
+    name: 'name',
+    role: 'editor',
   },
-  filter(compare('role', 'admin'))
+  { $filter: 'compare', path: 'role', operator: '=', match: 'admin' },
 ]
 ```
 
-#### `validate(path, schema)` helper
+#### `explode()` function
+
+Given an object, the `explode` helper function will return an array with one
+object for each property in the source object, with a `key` property for the
+property key, and a `value` property for the value.
+
+When given an array, the `explode` helper will return on object for every item
+in the array, with a `key` property set to the index number in the source array
+and a `value` property to the item value.
+
+When transforming in reverse, `explode` will try to compile an object or an
+array from an array of key/value objects. If all `key` props are numbers, an
+array is produced, otherwise an object. Anything that don't match the expected
+structure will be skipped.
+
+Example:
+
+```javascript
+import { mapTransform, transform, functions } from 'map-transform'
+const { explode } = functions
+
+const data = {
+  currencies: { NOK: 1, USD: 0.125, EUR: 0.1 },
+}
+
+const def32 = ['currencies', transform(explode())]
+
+mapTransform(def32)(data)
+// --> [{ key: 'NOK', value: 1 }, { key: 'USD', value: 0.125 },
+//      { key: 'EUR', value: 0.1 }]
+```
+
+Or as a transform object:
+
+```javascript
+const def32o = ['currencies', { $transform: 'explode' }]
+```
+
+#### `map(dictionary)` function
+
+This helper function accepts a dictionary described as an array of tuples, where
+each tuple holds a from value and a to value. When a data value is given to the
+`map` helper, it is replaced with a value from the dictionary. For a forward
+transformation, the first value in the tuple will be matched with the given
+data value, and the second value will be returned. In reverse transformation,
+the second value is matched and the first is returned.
+
+The wildcard value `*` will match any value, and is applied if there is no other
+match in the dictionary. When the returned value is `*`, the original data value
+is returned instead.
+
+The `map` function only supports primitive values, so any object will be mapped to
+`undefined` or the value given by the wildcard in the dictionary. Arrays will be
+iterated to map each value in the array.
+
+Example:
+
+```
+import { transform, functions } from 'map-transform'
+const { map } = functions
+
+const dictionary = [
+  [200, 'ok'],
+  [404, 'notfound'],
+  ['*', 'error']
+]
+
+const def28 = {
+  status: ['result', transform(map({ dictionary }))]
+}
+```
 
-This is a helper for validating the value at the path against a
+When using `map` in an operation object, you may provice a dictionary array
+or a named dictionary on the `dictionary` property. An example of with a named
+dictionary:
+
+```
+import { mapTransform } from 'map-transform'
+
+const dictionary = [
+  [200, 'ok'],
+  [404, 'notfound'],
+  ['*', 'error']
+]
+
+const def29 = {
+  status: [
+    'result',
+    { $transform: 'map', dictionary: 'statusCodes' }
+  ]
+}
+
+const mapper = mapTransform(def29, { dictionaries: { statusCodes: dictionary } })
+```
+
+#### `template(template)` function
+
+The `template` helper function takes a [handlebars] template and applies the
+given data to it. The placeholders in the template is dot notaion paths to
+fields in the given data. A simple dot (`.`) refers to the data itself, and may
+be useful when the pipeline data is a string.
+
+Values will be forced to strings before being inserted in the template.
+
+Example:
+
+```javascript
+import { mapTransform, transform, functions } from 'map-transform'
+const { template } = functions
+
+const data = {
+  content: { description: 'Bergen by night', artist: 'John F.' },
+}
+
+const def30 = {
+  caption: ['content', transform(template('{{description}}. By {{artist}}'))],
+}
+
+const ret = mapTransform(def30)(data)
+// --> { caption: 'Bergen by night. By John F.' }
+```
+
+The `template` function is also available through a transform object:
+
+```javascript
+const def30o = {
+  caption: [
+    'content',
+    { $transform: 'template', template: '{{description}}. By {{artist}}' },
+  ],
+}
+```
+
+If you the template is available as part of the data, you may use `templatePath`
+instead of `template`, and set it to the path of the template in the data. When
+using the transform object format, this is as simple as it sounds. With the
+function version, you supply an operand object to `template()` like this:
+`transform(template({ templatePath: 'options.captionTemplate' }))`.
+
+#### `validate(path, schema)` function
+
+This is a helper function for validating the value at the path against a
 [JSON Schema](http://json-schema.org). We won't go into details of JSON Schema
 here, and the `validate()` helper simply retrieves the value at the path and
 validates it according to the provided schema.
@@ -774,18 +1193,19 @@ Note that if you provide a schema that is always valid, it will be valid even
 when the data has no value at the given path.
 
 ```javascript
-import { filter, validate } from 'map-transform'
+import { filter, functions } from 'map-transform'
+const { validate } = functions
 
 const def20 = [
   'items',
   filter(validate('draft', { const: false })),
   {
-    title: 'heading'
-  }
+    title: 'heading',
+  },
 ]
 ```
 
-#### `not(value)` helper
+#### `not(value)` function
 
 `not()` will return `false` when value if truthy and `true` when value is falsy.
 This is useful for making the `filter()` operation do the opposite of what the
@@ -794,14 +1214,15 @@ filter function implies.
 Here we filter away all data where role is set to 'admin':
 
 ```javascript
-import { filter, compare } from 'map-transform'
+import { filter, functions } from 'map-transform'
+const { compare } = functions
 
 const def21 = [
   {
     name: 'name',
-    role: 'role'
+    role: 'role',
   },
-  filter(not(compare('role', 'admin')))
+  filter(not(compare('role', 'admin'))),
 ]
 ```
 
@@ -828,14 +1249,14 @@ const def22 = [
   'data.customers[]',
   {
     id: 'customerNo',
-    name: ['fullname', alt(value('Anonymous'))]
-  }
+    name: ['fullname', alt(value('Anonymous'))],
+  },
 ]
 
 const dataInTargetState = [
   { id: 'cust1', name: 'Fred Johnsen' },
-  { id: 'cust2', name: 'Lucy Knight' },
-  { id: 'cust3' }
+  // { id: 'cust2', name: 'Lucy Knight' },
+  { id: 'cust3' },
 ]
 
 const dataInSourceState = mapTransform(def22).rev(dataInTargetState)
@@ -861,15 +1282,15 @@ For example:
 ```javascript
 import { mapTransform, transform } from 'map-transform'
 
-const username = name => name.replace(/\s+/, '.').toLowerCase()
+const username = (name) => name.replace(/\s+/, '.').toLowerCase()
 
 const def23 = [
   'data.customers[]',
   {
     id: 'customerNo',
     name: 'fullname',
-    'name/1': ['username', rev(transform(username))]
-  }
+    'name/1': ['username', rev(transform(username))],
+  },
 ]
 
 const dataInTargetState = [{ id: 'cust1', name: 'Fred Johnsen' }]
@@ -884,6 +1305,60 @@ const dataInSourceState = mapTransform(def23).rev(dataInTargetState)
 // }
 ```
 
+In some cases, the reverse transform is more complex than the forward transform.
+For that reason, there is a `$flip` property that may be set to `true` on a
+transform object, to indicate that it is defined from the reverse perspective
+and should be flipped before running transformations.
+
+A flipped transformation object will – in forward transformations – get with the
+properties on the object and set with the paths in the value. The order of paths
+and operations in a pipeline will also be reversed. Note that this will not
+affect any operations that behaves differently depending on direction, and they
+will run as if they were used on a non-flipped transformation object.
+
+Also note that flipping will not affect the `get` and `set` operations, only
+path strings set directly as properties on the object or as part of the value
+(the pipeline). This might change in the future, so you should not use `get` and
+`set` directly on a flipped transformation object.
+
+This flipped defintion:
+
+```javascript
+const def33flipped = {
+  $flip: true,
+  id: 'key',
+  attributes: {
+    title: ['headline', transform(threeLetters)],
+    age: ['unknown'],
+  },
+  relationships: {
+    author: value('johnf'),
+  },
+}
+```
+
+... is identical to:
+
+```javascript
+const def33 = {
+  key: 'id',
+  headline: ['attributes.title', transform(threeLetters)],
+  unknown: ['attributes.age']
+  },
+  'none/1': ['relationships.author': value('johnf')]
+}
+```
+
+The flipped definition is (in this case) easier to read.
+
+Note also the `'none/1'` property in `def33`, that will stop this property from
+being set when going forward. This is not necessary on the flipped definition,
+but also results in a definition that will not work as expected going forward.
+This is a weakness in how MapTransform treats pipelines right now, and will
+probably be resolved in the future. For now, make sure to always have a path
+at the beginning of all pipelines if you plan to reverse transform – and the
+same goes for flipped transform objects if you want to forward transform.
+
 ### Mapping without fallbacks
 
 MapTransform will try its best to map the data it gets to the state you want,
@@ -905,7 +1380,7 @@ import { mapTransform, alt, value } from 'map-transform'
 
 const def24 = {
   id: 'customerNo',
-  name: ['fullname', alt(value('Anonymous'))]
+  name: ['fullname', alt(value('Anonymous'))],
 }
 
 const mapper = mapTransform(def24)